Skip to content

Commit cd57996

Browse files
drbraindrbrain
committed
Refactored most directives into RDoc::Markup::PreProcesor for
consistency Deprecated RDoc::Parser.process_directive
1 parent 9cc3a51 commit cd57996

File tree

7 files changed

+332
-239
lines changed

7 files changed

+332
-239
lines changed

‎lib/rdoc/markup/pre_process.rb‎

Lines changed: 103 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@
1313

1414
class RDoc::Markup::PreProcess
1515

16+
attr_accessor :options
17+
1618
@registered = {}
1719

1820
##
@@ -38,6 +40,7 @@ def self.registered
3840
def initialize(input_file_name, include_path)
3941
@input_file_name = input_file_name
4042
@include_path = include_path
43+
@options = nil
4144
end
4245

4346
##
@@ -54,68 +57,120 @@ def initialize(input_file_name, include_path)
5457
# If +code_object+ is given and the param is set as metadata on the
5558
# +code_object+. See RDoc::CodeObject#metadata
5659

57-
def handle text, code_object = nil
60+
def handle text, code_object = nil, &block
61+
encoding = if defined?(Encoding) then text.encoding else nil end
5862
# regexp helper (square brackets for optional)
5963
# $1 $2 $3 $4 $5
6064
# [prefix][\]:directive:[spaces][param]newline
61-
text.gsub!(/^([ \t]*#?[ \t]*)(\\?):(\w+):([ \t]*)(.+)?\n/) do
65+
text.gsub!(/^([ \t]*(?:#|\/?\*)?[ \t]*)(\\?):(\w+):([ \t]*)(.+)?\n/) do
6266
# skip something like ':toto::'
6367
next $& if $4.empty? and $5 and $5[0, 1] == ':'
6468

6569
# skip if escaped
6670
next "#$1:#$3:#$4#$5\n" unless $2.empty?
6771

68-
prefix = $1
69-
directive = $3.downcase
70-
param = $5
71-
72-
case directive
73-
when 'include' then
74-
filename = param.split[0]
75-
encoding = if defined?(Encoding) then text.encoding else nil end
76-
include_file filename, prefix, encoding
77-
when 'category' then
78-
if RDoc::Context === code_object then
79-
section = code_object.add_section param, ''
80-
code_object.temporary_section = section
81-
end
72+
handle_directive $1, $3, $5, code_object, encoding, &block
73+
end
74+
75+
text
76+
end
77+
78+
#--
79+
# When 1.8.7 support is ditched prefix can be defaulted to ''
80+
81+
def handle_directive prefix, directive, param, code_object = nil,
82+
encoding = nil
83+
blankline = "#{prefix.strip}\n"
84+
directive = directive.downcase
85+
86+
case directive
87+
when 'arg', 'args' then
88+
return blankline unless code_object
89+
90+
code_object.params = param
91+
92+
blankline
93+
when 'category' then
94+
if RDoc::Context === code_object then
95+
section = code_object.add_section param, ''
96+
code_object.temporary_section = section
97+
end
98+
99+
blankline # ignore category if we're not on an RDoc::Context
100+
when 'doc' then
101+
return blankline unless code_object
102+
code_object.document_self = true
103+
code_object.force_documentation = true
104+
105+
blankline
106+
when 'enddoc' then
107+
return blankline unless code_object
108+
code_object.done_documenting = true
109+
110+
blankline
111+
when 'include' then
112+
filename = param.split.first
113+
include_file filename, prefix, encoding
114+
when 'main' then
115+
@options.main_page = param if @options.respond_to? :main_page
116+
117+
blankline
118+
when 'nodoc' then
119+
return blankline unless code_object
120+
code_object.document_self = nil # notify nodoc
121+
code_object.document_children = param.to_s.downcase != 'all'
82122

83-
'' # ignore category if we're not on an RDoc::Context
84-
when 'doc' then
85-
next unless code_object
86-
code_object.document_self = true
87-
code_object.force_documentation = true
88-
when 'nodoc' then
89-
next unless code_object
90-
code_object.document_self = nil # notify nodoc
91-
code_object.document_children = param.to_s.downcase != 'all'
92-
when 'yield', 'yields' then
93-
next unless code_object
94-
# remove parameter &block
95-
code_object.params.sub!(/,?\s*&\w+/, '') if code_object.params
96-
97-
code_object.block_params = param
98-
else
99-
result = yield directive, param if block_given?
100-
101-
case result
102-
when nil then
103-
code_object.metadata[directive] = param if code_object
104-
if RDoc::Markup::PreProcess.registered.include? directive then
105-
handler = RDoc::Markup::PreProcess.registered[directive]
106-
result = handler.call directive, param if handler
107-
else
108-
result = "#{prefix}:#{directive}: #{param}\n"
109-
end
110-
when false then
123+
blankline
124+
when 'notnew', 'not_new', 'not-new' then
125+
return blankline unless RDoc::AnyMethod === code_object
126+
127+
code_object.dont_rename_initialize = true
128+
129+
blankline
130+
when 'startdoc' then
131+
return blankline unless code_object
132+
133+
code_object.start_doc
134+
code_object.force_documentation = true
135+
136+
blankline
137+
when 'stopdoc' then
138+
return blankline unless code_object
139+
140+
code_object.stop_doc
141+
142+
blankline
143+
when 'title' then
144+
@options.default_title = param if @options.respond_to? :default_title=
145+
146+
blankline
147+
when 'yield', 'yields' then
148+
return blankline unless code_object
149+
# remove parameter &block
150+
code_object.params.sub!(/,?\s*&\w+/, '') if code_object.params
151+
152+
code_object.block_params = param
153+
154+
blankline
155+
else
156+
result = yield directive, param if block_given?
157+
158+
case result
159+
when nil then
160+
code_object.metadata[directive] = param if code_object
161+
162+
if RDoc::Markup::PreProcess.registered.include? directive then
163+
handler = RDoc::Markup::PreProcess.registered[directive]
164+
result = handler.call directive, param if handler
165+
else
111166
result = "#{prefix}:#{directive}: #{param}\n"
112167
end
113-
114-
result
168+
when false then
169+
result = "#{prefix}:#{directive}: #{param}\n"
115170
end
116-
end
117171

118-
text
172+
result
173+
end
119174
end
120175

121176
##

‎lib/rdoc/parser.rb‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,8 @@ def self.binary?(file)
106106
# Applies +directive+'s +value+ to +code_object+, if appropriate
107107

108108
def self.process_directive code_object, directive, value
109+
warn "RDoc::Parser::process_directive is deprecated and wil be removed in RDoc 4. Use RDoc::Markup::PreProcess#handle_directive instead" if $-w
110+
109111
case directive
110112
when 'nodoc' then
111113
code_object.document_self = nil # notify nodoc
@@ -196,6 +198,9 @@ def initialize(top_level, file_name, content, options, stats)
196198
@content = content
197199
@options = options
198200
@stats = stats
201+
202+
@preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include
203+
@preprocess.options = @options
199204
end
200205

201206
end

‎lib/rdoc/parser/c.rb‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -645,9 +645,7 @@ def find_modifiers comment, meth_obj
645645
meth_obj.call_seq = $1.strip
646646
end
647647

648-
if comment.sub!(/\s*:(nodoc|doc|yields?|args?):\s*(.*)/, '') then
649-
RDoc::Parser.process_directive meth_obj, $1, $2
650-
end
648+
look_for_directives_in meth_obj, comment
651649
end
652650

653651
##
@@ -913,12 +911,10 @@ def handle_tab_width(body)
913911
# * :title: My Awesome Project
914912
# */
915913
#
916-
# This routine modifies its parameter
917-
918-
def look_for_directives_in(context, comment)
919-
preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include
914+
# This method modifies the +comment+
920915

921-
preprocess.handle comment, context do |directive, param|
916+
def look_for_directives_in context, comment
917+
@preprocess.handle comment, context do |directive, param|
922918
case directive
923919
when 'main' then
924920
@options.main_page = param

‎lib/rdoc/parser/ruby.rb‎

Lines changed: 8 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -406,33 +406,15 @@ def get_symbol_or_name
406406
# This routine modifies its +comment+ parameter.
407407

408408
def look_for_directives_in(context, comment)
409-
preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include
410-
411-
preprocess.handle comment, context do |directive, param|
409+
@preprocess.handle comment, context do |directive, param|
412410
case directive
413-
when 'enddoc' then
414-
context.done_documenting = true
415-
''
416-
when 'main' then
417-
@options.main_page = param if @options.respond_to? :main_page
418-
''
419411
when 'method', 'singleton-method',
420412
'attr', 'attr_accessor', 'attr_reader', 'attr_writer' then
421413
false # handled elsewhere
422414
when 'section' then
423415
context.set_current_section param, comment
424416
comment.replace ''
425417
break
426-
when 'startdoc' then
427-
context.start_doc
428-
context.force_documentation = true
429-
''
430-
when 'stopdoc' then
431-
context.stop_doc
432-
''
433-
when 'title' then
434-
@options.default_title = param if @options.respond_to? :default_title=
435-
''
436418
end
437419
end
438420

@@ -1643,16 +1625,17 @@ def read_directive allowed
16431625
# Handles the directive for +context+ if the directive is listed in +allow+.
16441626
# This method is called for directives following a definition.
16451627

1646-
def read_documentation_modifiers(context, allow)
1628+
def read_documentation_modifiers context, allow
16471629
directive, value = read_directive allow
16481630

16491631
return unless directive
16501632

1651-
case directive
1652-
when 'notnew', 'not_new', 'not-new' then
1653-
context.dont_rename_initialize = true
1654-
else
1655-
RDoc::Parser.process_directive context, directive, value
1633+
@preprocess.handle_directive '', directive, value, context do |directive, param|
1634+
if %w[notnew not_new not-new].include? directive then
1635+
context.dont_rename_initialize = true
1636+
1637+
true
1638+
end
16561639
end
16571640
end
16581641

‎lib/rdoc/parser/ruby_tools.rb‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,8 @@ def unget_tk(tk)
153153
@token_listeners.each do |obj|
154154
obj.pop_token
155155
end if @token_listeners
156+
157+
nil
156158
end
157159

158160
end

0 commit comments

Comments
 (0)