rdoc 6.4.0 → 6.6.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CONTRIBUTING.rdoc +1 -2
- data/LEGAL.rdoc +1 -1
- data/README.rdoc +2 -2
- data/TODO.rdoc +1 -1
- data/exe/rdoc +0 -1
- data/lib/rdoc/alias.rb +0 -1
- data/lib/rdoc/anon_class.rb +0 -1
- data/lib/rdoc/any_method.rb +17 -2
- data/lib/rdoc/attr.rb +0 -1
- data/lib/rdoc/class_module.rb +0 -1
- data/lib/rdoc/code_objects.rb +1 -2
- data/lib/rdoc/comment.rb +20 -41
- data/lib/rdoc/constant.rb +0 -1
- data/lib/rdoc/context/section.rb +2 -1
- data/lib/rdoc/context.rb +1 -3
- data/lib/rdoc/cross_reference.rb +17 -2
- data/lib/rdoc/encoding.rb +1 -6
- data/lib/rdoc/erb_partial.rb +0 -1
- data/lib/rdoc/erbio.rb +2 -7
- data/lib/rdoc/extend.rb +0 -1
- data/lib/rdoc/generator/darkfish.rb +2 -6
- data/lib/rdoc/generator/json_index.rb +2 -2
- data/lib/rdoc/generator/markup.rb +1 -2
- data/lib/rdoc/generator/ri.rb +0 -1
- data/lib/rdoc/generator/template/darkfish/_head.rhtml +10 -10
- data/lib/rdoc/generator/template/darkfish/_sidebar_classes.rhtml +27 -3
- data/lib/rdoc/generator/template/darkfish/_sidebar_pages.rhtml +22 -2
- data/lib/rdoc/generator/template/darkfish/_sidebar_search.rhtml +1 -1
- data/lib/rdoc/generator/template/darkfish/_sidebar_table_of_contents.rhtml +25 -4
- data/lib/rdoc/generator/template/darkfish/class.rhtml +28 -20
- data/lib/rdoc/generator/template/darkfish/css/rdoc.css +44 -7
- data/lib/rdoc/generator/template/darkfish/index.rhtml +1 -1
- data/lib/rdoc/generator/template/darkfish/js/darkfish.js +14 -1
- data/lib/rdoc/generator/template/darkfish/js/search.js +4 -4
- data/lib/rdoc/generator/template/darkfish/table_of_contents.rhtml +7 -6
- data/lib/rdoc/generator/template/json_index/js/navigation.js +8 -8
- data/lib/rdoc/generator.rb +5 -5
- data/lib/rdoc/ghost_method.rb +0 -1
- data/lib/rdoc/i18n.rb +1 -1
- data/lib/rdoc/include.rb +0 -1
- data/lib/rdoc/known_classes.rb +5 -4
- data/lib/rdoc/markdown/entities.rb +0 -1
- data/lib/rdoc/markdown/literals.rb +98 -40
- data/lib/rdoc/markdown.kpeg +26 -19
- data/lib/rdoc/markdown.rb +326 -227
- data/lib/rdoc/markup/attr_changer.rb +0 -1
- data/lib/rdoc/markup/attr_span.rb +0 -1
- data/lib/rdoc/markup/attribute_manager.rb +29 -36
- data/lib/rdoc/markup/attributes.rb +0 -1
- data/lib/rdoc/markup/blank_line.rb +0 -1
- data/lib/rdoc/markup/block_quote.rb +0 -1
- data/lib/rdoc/markup/document.rb +0 -1
- data/lib/rdoc/markup/formatter.rb +0 -1
- data/lib/rdoc/markup/hard_break.rb +0 -1
- data/lib/rdoc/markup/heading.rb +0 -1
- data/lib/rdoc/markup/include.rb +0 -1
- data/lib/rdoc/markup/indented_paragraph.rb +0 -1
- data/lib/rdoc/markup/list.rb +0 -1
- data/lib/rdoc/markup/list_item.rb +0 -1
- data/lib/rdoc/markup/paragraph.rb +0 -1
- data/lib/rdoc/markup/parser.rb +12 -6
- data/lib/rdoc/markup/raw.rb +0 -1
- data/lib/rdoc/markup/regexp_handling.rb +0 -1
- data/lib/rdoc/markup/rule.rb +0 -1
- data/lib/rdoc/markup/to_ansi.rb +0 -1
- data/lib/rdoc/markup/to_html.rb +21 -16
- data/lib/rdoc/markup/to_html_crossref.rb +0 -1
- data/lib/rdoc/markup/to_html_snippet.rb +0 -1
- data/lib/rdoc/markup/to_joined_paragraph.rb +2 -3
- data/lib/rdoc/markup/to_label.rb +1 -2
- data/lib/rdoc/markup/to_markdown.rb +0 -1
- data/lib/rdoc/markup/to_rdoc.rb +3 -21
- data/lib/rdoc/markup/to_table_of_contents.rb +0 -1
- data/lib/rdoc/markup/to_test.rb +0 -1
- data/lib/rdoc/markup/to_tt_only.rb +0 -1
- data/lib/rdoc/markup/verbatim.rb +0 -1
- data/lib/rdoc/markup.rb +35 -667
- data/lib/rdoc/meta_method.rb +0 -1
- data/lib/rdoc/method_attr.rb +1 -2
- data/lib/rdoc/mixin.rb +0 -1
- data/lib/rdoc/normal_class.rb +1 -2
- data/lib/rdoc/normal_module.rb +1 -2
- data/lib/rdoc/options.rb +36 -20
- data/lib/rdoc/parser/c.rb +89 -101
- data/lib/rdoc/parser/changelog.rb +0 -1
- data/lib/rdoc/parser/markdown.rb +0 -2
- data/lib/rdoc/parser/rd.rb +0 -1
- data/lib/rdoc/parser/ripper_state_lex.rb +1 -1
- data/lib/rdoc/parser/ruby.rb +29 -14
- data/lib/rdoc/parser/ruby_tools.rb +0 -2
- data/lib/rdoc/parser/text.rb +0 -1
- data/lib/rdoc/parser.rb +19 -2
- data/lib/rdoc/rd/block_parser.rb +666 -12
- data/lib/rdoc/rd/block_parser.ry +13 -9
- data/lib/rdoc/rd/inline.rb +0 -1
- data/lib/rdoc/rd/inline_parser.rb +3 -1
- data/lib/rdoc/rd.rb +3 -4
- data/lib/rdoc/rdoc.rb +19 -7
- data/lib/rdoc/require.rb +0 -1
- data/lib/rdoc/ri/driver.rb +20 -86
- data/lib/rdoc/ri/store.rb +0 -1
- data/lib/rdoc/ri.rb +4 -5
- data/lib/rdoc/rubygems_hook.rb +1 -1
- data/lib/rdoc/servlet.rb +1 -1
- data/lib/rdoc/single_class.rb +5 -1
- data/lib/rdoc/stats/quiet.rb +0 -1
- data/lib/rdoc/stats/verbose.rb +0 -2
- data/lib/rdoc/stats.rb +3 -4
- data/lib/rdoc/store.rb +4 -4
- data/lib/rdoc/task.rb +31 -5
- data/lib/rdoc/token_stream.rb +0 -1
- data/lib/rdoc/top_level.rb +0 -1
- data/lib/rdoc/version.rb +3 -1
- data/lib/rdoc.rb +46 -46
- metadata +9 -11
- data/Gemfile +0 -12
- data/Rakefile +0 -107
- data/bin/console +0 -7
- data/bin/setup +0 -6
- data/rdoc.gemspec +0 -249
data/lib/rdoc/markup.rb
CHANGED
@@ -97,638 +97,7 @@
|
|
97
97
|
#
|
98
98
|
# = \RDoc Markup Reference
|
99
99
|
#
|
100
|
-
#
|
101
|
-
#
|
102
|
-
# === Paragraphs and Verbatim
|
103
|
-
#
|
104
|
-
# The markup engine looks for a document's natural left margin. This is
|
105
|
-
# used as the initial margin for the document.
|
106
|
-
#
|
107
|
-
# Consecutive lines starting at this margin are considered to be a
|
108
|
-
# paragraph. Empty lines separate paragraphs.
|
109
|
-
#
|
110
|
-
# Any line that starts to the right of the current margin is treated
|
111
|
-
# as verbatim text. This is useful for code listings:
|
112
|
-
#
|
113
|
-
# 3.times { puts "Ruby" }
|
114
|
-
#
|
115
|
-
# In verbatim text, two or more blank lines are collapsed into one,
|
116
|
-
# and trailing blank lines are removed:
|
117
|
-
#
|
118
|
-
# This is the first line
|
119
|
-
#
|
120
|
-
#
|
121
|
-
# This is the second non-blank line,
|
122
|
-
# after 2 blank lines in the source markup.
|
123
|
-
#
|
124
|
-
#
|
125
|
-
# There were two trailing blank lines right above this paragraph, that
|
126
|
-
# have been removed. In addition, the verbatim text has been shifted
|
127
|
-
# left, so the amount of indentation of verbatim text is unimportant.
|
128
|
-
#
|
129
|
-
# For HTML output RDoc makes a small effort to determine if a verbatim section
|
130
|
-
# contains Ruby source code. If so, the verbatim block will be marked up as
|
131
|
-
# HTML. Triggers include "def", "class", "module", "require", the "hash
|
132
|
-
# rocket"# (=>) or a block call with a parameter.
|
133
|
-
#
|
134
|
-
# === Headers
|
135
|
-
#
|
136
|
-
# A line starting with an equal sign (=) is treated as a
|
137
|
-
# heading. Level one headings have one equals sign, level two headings
|
138
|
-
# have two, and so on until level six, which is the maximum
|
139
|
-
# (seven hyphens or more result in a level six heading).
|
140
|
-
#
|
141
|
-
# For example, the above header was obtained with:
|
142
|
-
#
|
143
|
-
# === Headers
|
144
|
-
#
|
145
|
-
# In HTML output headers have an id matching their name. The above example's
|
146
|
-
# HTML is:
|
147
|
-
#
|
148
|
-
# <h3 id="label-Headers">Headers</h3>
|
149
|
-
#
|
150
|
-
# If a heading is inside a method body the id will be prefixed with the
|
151
|
-
# method's id. If the above header where in the documentation for a method
|
152
|
-
# such as:
|
153
|
-
#
|
154
|
-
# ##
|
155
|
-
# # This method does fun things
|
156
|
-
# #
|
157
|
-
# # = Example
|
158
|
-
# #
|
159
|
-
# # Example of fun things goes here ...
|
160
|
-
#
|
161
|
-
# def do_fun_things
|
162
|
-
# end
|
163
|
-
#
|
164
|
-
# The header's id would be:
|
165
|
-
#
|
166
|
-
# <h1 id="method-i-do_fun_things-label-Example">Example</h1>
|
167
|
-
#
|
168
|
-
# The label can be linked-to using <tt>SomeClass@Headers</tt>. See
|
169
|
-
# {Links}[RDoc::Markup@Links] for further details.
|
170
|
-
#
|
171
|
-
# === Rules
|
172
|
-
#
|
173
|
-
# A line starting with three or more hyphens (at the current indent)
|
174
|
-
# generates a horizontal rule.
|
175
|
-
#
|
176
|
-
# ---
|
177
|
-
#
|
178
|
-
# produces:
|
179
|
-
#
|
180
|
-
# ---
|
181
|
-
#
|
182
|
-
# === Simple Lists
|
183
|
-
#
|
184
|
-
# If a paragraph starts with a "*", "-", "<digit>." or "<letter>.",
|
185
|
-
# then it is taken to be the start of a list. The margin is increased to be
|
186
|
-
# the first non-space following the list start flag. Subsequent lines
|
187
|
-
# should be indented to this new margin until the list ends. For example:
|
188
|
-
#
|
189
|
-
# * this is a list with three paragraphs in
|
190
|
-
# the first item. This is the first paragraph.
|
191
|
-
#
|
192
|
-
# And this is the second paragraph.
|
193
|
-
#
|
194
|
-
# 1. This is an indented, numbered list.
|
195
|
-
# 2. This is the second item in that list
|
196
|
-
#
|
197
|
-
# This is the third conventional paragraph in the
|
198
|
-
# first list item.
|
199
|
-
#
|
200
|
-
# * This is the second item in the original list
|
201
|
-
#
|
202
|
-
# produces:
|
203
|
-
#
|
204
|
-
# * this is a list with three paragraphs in
|
205
|
-
# the first item. This is the first paragraph.
|
206
|
-
#
|
207
|
-
# And this is the second paragraph.
|
208
|
-
#
|
209
|
-
# 1. This is an indented, numbered list.
|
210
|
-
# 2. This is the second item in that list
|
211
|
-
#
|
212
|
-
# This is the third conventional paragraph in the
|
213
|
-
# first list item.
|
214
|
-
#
|
215
|
-
# * This is the second item in the original list
|
216
|
-
#
|
217
|
-
# === Labeled Lists
|
218
|
-
#
|
219
|
-
# You can also construct labeled lists, sometimes called description
|
220
|
-
# or definition lists. Do this by putting the label in square brackets
|
221
|
-
# and indenting the list body:
|
222
|
-
#
|
223
|
-
# [cat] a small furry mammal
|
224
|
-
# that seems to sleep a lot
|
225
|
-
#
|
226
|
-
# [ant] a little insect that is known
|
227
|
-
# to enjoy picnics
|
228
|
-
#
|
229
|
-
# produces:
|
230
|
-
#
|
231
|
-
# [cat] a small furry mammal
|
232
|
-
# that seems to sleep a lot
|
233
|
-
#
|
234
|
-
# [ant] a little insect that is known
|
235
|
-
# to enjoy picnics
|
236
|
-
#
|
237
|
-
# If you want the list bodies to line up to the left of the labels,
|
238
|
-
# use two colons:
|
239
|
-
#
|
240
|
-
# cat:: a small furry mammal
|
241
|
-
# that seems to sleep a lot
|
242
|
-
#
|
243
|
-
# ant:: a little insect that is known
|
244
|
-
# to enjoy picnics
|
245
|
-
#
|
246
|
-
# produces:
|
247
|
-
#
|
248
|
-
# cat:: a small furry mammal
|
249
|
-
# that seems to sleep a lot
|
250
|
-
#
|
251
|
-
# ant:: a little insect that is known
|
252
|
-
# to enjoy picnics
|
253
|
-
#
|
254
|
-
# Notice that blank lines right after the label are ignored in labeled lists:
|
255
|
-
#
|
256
|
-
# [one]
|
257
|
-
#
|
258
|
-
# definition 1
|
259
|
-
#
|
260
|
-
# [two]
|
261
|
-
#
|
262
|
-
# definition 2
|
263
|
-
#
|
264
|
-
# produces the same output as
|
265
|
-
#
|
266
|
-
# [one] definition 1
|
267
|
-
# [two] definition 2
|
268
|
-
#
|
269
|
-
#
|
270
|
-
# === Lists and Verbatim
|
271
|
-
#
|
272
|
-
# If you want to introduce a verbatim section right after a list, it has to be
|
273
|
-
# less indented than the list item bodies, but more indented than the list
|
274
|
-
# label, letter, digit or bullet. For instance:
|
275
|
-
#
|
276
|
-
# * point 1
|
277
|
-
#
|
278
|
-
# * point 2, first paragraph
|
279
|
-
#
|
280
|
-
# point 2, second paragraph
|
281
|
-
# verbatim text inside point 2
|
282
|
-
# point 2, third paragraph
|
283
|
-
# verbatim text outside of the list (the list is therefore closed)
|
284
|
-
# regular paragraph after the list
|
285
|
-
#
|
286
|
-
# produces:
|
287
|
-
#
|
288
|
-
# * point 1
|
289
|
-
#
|
290
|
-
# * point 2, first paragraph
|
291
|
-
#
|
292
|
-
# point 2, second paragraph
|
293
|
-
# verbatim text inside point 2
|
294
|
-
# point 2, third paragraph
|
295
|
-
# verbatim text outside of the list (the list is therefore closed)
|
296
|
-
# regular paragraph after the list
|
297
|
-
#
|
298
|
-
# == Text Markup
|
299
|
-
#
|
300
|
-
# === Bold, Italic, Typewriter Text
|
301
|
-
#
|
302
|
-
# You can use markup within text (except verbatim) to change the
|
303
|
-
# appearance of parts of that text. Out of the box, RDoc::Markup
|
304
|
-
# supports word-based and general markup.
|
305
|
-
#
|
306
|
-
# Word-based markup uses flag characters around individual words:
|
307
|
-
#
|
308
|
-
# <tt>\*_word_\*</tt>:: displays _word_ in a *bold* font
|
309
|
-
# <tt>\__word_\_</tt>:: displays _word_ in an _emphasized_ font
|
310
|
-
# <tt>\+_word_\+</tt>:: displays _word_ in a +code+ font
|
311
|
-
#
|
312
|
-
# General markup affects text between a start delimiter and an end
|
313
|
-
# delimiter. Not surprisingly, these delimiters look like HTML markup.
|
314
|
-
#
|
315
|
-
# <tt>\<b>_text_</b></tt>:: displays _text_ in a *bold* font
|
316
|
-
# <tt>\<em>_text_</em></tt>:: displays _text_ in an _emphasized_ font
|
317
|
-
# (alternate tag: <tt>\<i></tt>)
|
318
|
-
# <tt>\<tt>_text_\</tt></tt>:: displays _text_ in a +code+ font
|
319
|
-
# (alternate tag: <tt>\<code></tt>)
|
320
|
-
#
|
321
|
-
# Unlike conventional Wiki markup, general markup can cross line
|
322
|
-
# boundaries. You can turn off the interpretation of markup by
|
323
|
-
# preceding the first character with a backslash (see <i>Escaping
|
324
|
-
# Text Markup</i>, below).
|
325
|
-
#
|
326
|
-
# === Links
|
327
|
-
#
|
328
|
-
# Links to starting with +http:+, +https:+, +mailto:+, +ftp:+ or +www.+
|
329
|
-
# are recognized. An HTTP url that references an external image is converted
|
330
|
-
# into an inline image element.
|
331
|
-
#
|
332
|
-
# Classes and methods will be automatically linked to their definition. For
|
333
|
-
# example, <tt>RDoc::Markup</tt> will link to this documentation. By default
|
334
|
-
# methods will only be automatically linked if they contain an <tt>_</tt> (all
|
335
|
-
# methods can be automatically linked through the <tt>--hyperlink-all</tt>
|
336
|
-
# command line option).
|
337
|
-
#
|
338
|
-
# Single-word methods can be linked by using the <tt>#</tt> character for
|
339
|
-
# instance methods or <tt>::</tt> for class methods. For example,
|
340
|
-
# <tt>#convert</tt> links to #convert. A class or method may be combined like
|
341
|
-
# <tt>RDoc::Markup#convert</tt>.
|
342
|
-
#
|
343
|
-
# A heading inside the documentation can be linked by following the class
|
344
|
-
# or method by an <tt>@</tt> then the heading name.
|
345
|
-
# <tt>RDoc::Markup@Links</tt> will link to this section like this:
|
346
|
-
# RDoc::Markup@Links. Spaces in headings with multiple words must be escaped
|
347
|
-
# with <tt>+</tt> like <tt>RDoc::Markup@Escaping+Text+Markup</tt>.
|
348
|
-
# Punctuation and other special characters must be escaped like CGI.escape.
|
349
|
-
#
|
350
|
-
# The <tt>@</tt> can also be used to link to sections. If a section and a
|
351
|
-
# heading share the same name the section is preferred for the link.
|
352
|
-
#
|
353
|
-
# Links can also be of the form <tt>label[url]</tt>, in which case +label+ is
|
354
|
-
# used in the displayed text, and +url+ is used as the target. If +label+
|
355
|
-
# contains multiple words, put it in braces: <tt>{multi word label}[url]</tt>.
|
356
|
-
# The +url+ may be an +http:+-type link or a cross-reference to a class,
|
357
|
-
# module or method with a label.
|
358
|
-
#
|
359
|
-
# Links with the <code>rdoc-image:</code> scheme will create an image tag for
|
360
|
-
# HTML output. Only fully-qualified URLs are supported.
|
361
|
-
#
|
362
|
-
# Links with the <tt>rdoc-ref:</tt> scheme will link to the referenced class,
|
363
|
-
# module, method, file, etc. If the referenced item is does not exist
|
364
|
-
# no link will be generated and <tt>rdoc-ref:</tt> will be removed from the
|
365
|
-
# resulting text.
|
366
|
-
#
|
367
|
-
# Links starting with <tt>rdoc-label:label_name</tt> will link to the
|
368
|
-
# +label_name+. You can create a label for the current link (for
|
369
|
-
# bidirectional links) by supplying a name for the current link like
|
370
|
-
# <tt>rdoc-label:label-other:label-mine</tt>.
|
371
|
-
#
|
372
|
-
# Links starting with +link:+ refer to local files whose path is relative to
|
373
|
-
# the <tt>--op</tt> directory. Use <tt>rdoc-ref:</tt> instead of
|
374
|
-
# <tt>link:</tt> to link to files generated by RDoc as the link target may
|
375
|
-
# be different across RDoc generators.
|
376
|
-
#
|
377
|
-
# Example links:
|
378
|
-
#
|
379
|
-
# https://github.com/ruby/rdoc
|
380
|
-
# mailto:user@example.com
|
381
|
-
# {RDoc Documentation}[http://rdoc.rubyforge.org]
|
382
|
-
# {RDoc Markup}[rdoc-ref:RDoc::Markup]
|
383
|
-
#
|
384
|
-
# === Escaping Text Markup
|
385
|
-
#
|
386
|
-
# Text markup can be escaped with a backslash, as in \<tt>, which was obtained
|
387
|
-
# with <tt>\\<tt></tt>. Except in verbatim sections and between \<tt> tags,
|
388
|
-
# to produce a backslash you have to double it unless it is followed by a
|
389
|
-
# space, tab or newline. Otherwise, the HTML formatter will discard it, as it
|
390
|
-
# is used to escape potential links:
|
391
|
-
#
|
392
|
-
# * The \ must be doubled if not followed by white space: \\.
|
393
|
-
# * But not in \<tt> tags: in a Regexp, <tt>\S</tt> matches non-space.
|
394
|
-
# * This is a link to {ruby-lang}[www.ruby-lang.org].
|
395
|
-
# * This is not a link, however: \{ruby-lang.org}[www.ruby-lang.org].
|
396
|
-
# * This will not be linked to \RDoc::RDoc#document
|
397
|
-
#
|
398
|
-
# generates:
|
399
|
-
#
|
400
|
-
# * The \ must be doubled if not followed by white space: \\.
|
401
|
-
# * But not in \<tt> tags: in a Regexp, <tt>\S</tt> matches non-space.
|
402
|
-
# * This is a link to {ruby-lang}[www.ruby-lang.org]
|
403
|
-
# * This is not a link, however: \{ruby-lang.org}[www.ruby-lang.org]
|
404
|
-
# * This will not be linked to \RDoc::RDoc#document
|
405
|
-
#
|
406
|
-
# Inside \<tt> tags, more precisely, leading backslashes are removed only if
|
407
|
-
# followed by a markup character (<tt><*_+</tt>), a backslash, or a known link
|
408
|
-
# reference (a known class or method). So in the example above, the backslash
|
409
|
-
# of <tt>\S</tt> would be removed if there was a class or module named +S+ in
|
410
|
-
# the current context.
|
411
|
-
#
|
412
|
-
# This behavior is inherited from RDoc version 1, and has been kept for
|
413
|
-
# compatibility with existing RDoc documentation.
|
414
|
-
#
|
415
|
-
# === Conversion of characters
|
416
|
-
#
|
417
|
-
# HTML will convert two/three dashes to an em-dash. Other common characters are
|
418
|
-
# converted as well:
|
419
|
-
#
|
420
|
-
# em-dash:: -- or ---
|
421
|
-
# ellipsis:: ...
|
422
|
-
#
|
423
|
-
# single quotes:: 'text' or `text'
|
424
|
-
# double quotes:: "text" or ``text''
|
425
|
-
#
|
426
|
-
# copyright:: (c)
|
427
|
-
# registered trademark:: (r)
|
428
|
-
#
|
429
|
-
# produces:
|
430
|
-
#
|
431
|
-
# em-dash:: -- or ---
|
432
|
-
# ellipsis:: ...
|
433
|
-
#
|
434
|
-
# single quotes:: 'text' or `text'
|
435
|
-
# double quotes:: "text" or ``text''
|
436
|
-
#
|
437
|
-
# copyright:: (c)
|
438
|
-
# registered trademark:: (r)
|
439
|
-
#
|
440
|
-
#
|
441
|
-
# == Documenting Source Code
|
442
|
-
#
|
443
|
-
# Comment blocks can be written fairly naturally, either using <tt>#</tt> on
|
444
|
-
# successive lines of the comment, or by including the comment in
|
445
|
-
# a <tt>=begin</tt>/<tt>=end</tt> block. If you use the latter form,
|
446
|
-
# the <tt>=begin</tt> line _must_ be flagged with an +rdoc+ tag:
|
447
|
-
#
|
448
|
-
# =begin rdoc
|
449
|
-
# Documentation to be processed by RDoc.
|
450
|
-
#
|
451
|
-
# ...
|
452
|
-
# =end
|
453
|
-
#
|
454
|
-
# RDoc stops processing comments if it finds a comment line starting
|
455
|
-
# with <tt>--</tt> right after the <tt>#</tt> character (otherwise,
|
456
|
-
# it will be treated as a rule if it has three dashes or more).
|
457
|
-
# This can be used to separate external from internal comments,
|
458
|
-
# or to stop a comment being associated with a method, class, or module.
|
459
|
-
# Commenting can be turned back on with a line that starts with <tt>++</tt>.
|
460
|
-
#
|
461
|
-
# ##
|
462
|
-
# # Extract the age and calculate the date-of-birth.
|
463
|
-
# #--
|
464
|
-
# # FIXME: fails if the birthday falls on February 29th
|
465
|
-
# #++
|
466
|
-
# # The DOB is returned as a Time object.
|
467
|
-
#
|
468
|
-
# def get_dob(person)
|
469
|
-
# # ...
|
470
|
-
# end
|
471
|
-
#
|
472
|
-
# Names of classes, files, and any method names containing an underscore or
|
473
|
-
# preceded by a hash character are automatically linked from comment text to
|
474
|
-
# their description. This linking works inside the current class or module,
|
475
|
-
# and with ancestor methods (in included modules or in the superclass).
|
476
|
-
#
|
477
|
-
# Method parameter lists are extracted and displayed with the method
|
478
|
-
# description. If a method calls +yield+, then the parameters passed to yield
|
479
|
-
# will also be displayed:
|
480
|
-
#
|
481
|
-
# def fred
|
482
|
-
# ...
|
483
|
-
# yield line, address
|
484
|
-
#
|
485
|
-
# This will get documented as:
|
486
|
-
#
|
487
|
-
# fred() { |line, address| ... }
|
488
|
-
#
|
489
|
-
# You can override this using a comment containing ':yields: ...' immediately
|
490
|
-
# after the method definition
|
491
|
-
#
|
492
|
-
# def fred # :yields: index, position
|
493
|
-
# # ...
|
494
|
-
#
|
495
|
-
# yield line, address
|
496
|
-
#
|
497
|
-
# which will get documented as
|
498
|
-
#
|
499
|
-
# fred() { |index, position| ... }
|
500
|
-
#
|
501
|
-
# +:yields:+ is an example of a documentation directive. These appear
|
502
|
-
# immediately after the start of the document element they are modifying.
|
503
|
-
#
|
504
|
-
# RDoc automatically cross-references words with underscores or camel-case.
|
505
|
-
# To suppress cross-references, prefix the word with a \ character. To
|
506
|
-
# include special characters like "<tt>\n</tt>", you'll need to use
|
507
|
-
# two \ characters in normal text, but only one in \<tt> text:
|
508
|
-
#
|
509
|
-
# "\\n" or "<tt>\n</tt>"
|
510
|
-
#
|
511
|
-
# produces:
|
512
|
-
#
|
513
|
-
# "\\n" or "<tt>\n</tt>"
|
514
|
-
#
|
515
|
-
# == Directives
|
516
|
-
#
|
517
|
-
# Directives are keywords surrounded by ":" characters.
|
518
|
-
#
|
519
|
-
# === Controlling what is documented
|
520
|
-
#
|
521
|
-
# [+:nodoc:+ / <tt>:nodoc: all</tt>]
|
522
|
-
# This directive prevents documentation for the element from
|
523
|
-
# being generated. For classes and modules, methods, aliases,
|
524
|
-
# constants, and attributes directly within the affected class or
|
525
|
-
# module also will be omitted. By default, though, modules and
|
526
|
-
# classes within that class or module _will_ be documented. This is
|
527
|
-
# turned off by adding the +all+ modifier.
|
528
|
-
#
|
529
|
-
# module MyModule # :nodoc:
|
530
|
-
# class Input
|
531
|
-
# end
|
532
|
-
# end
|
533
|
-
#
|
534
|
-
# module OtherModule # :nodoc: all
|
535
|
-
# class Output
|
536
|
-
# end
|
537
|
-
# end
|
538
|
-
#
|
539
|
-
# In the above code, only class <tt>MyModule::Input</tt> will be documented.
|
540
|
-
#
|
541
|
-
# The +:nodoc:+ directive, like +:enddoc:+, +:stopdoc:+ and +:startdoc:+
|
542
|
-
# presented below, is local to the current file: if you do not want to
|
543
|
-
# document a module that appears in several files, specify +:nodoc:+ on each
|
544
|
-
# appearance, at least once per file.
|
545
|
-
#
|
546
|
-
# [+:stopdoc:+ / +:startdoc:+]
|
547
|
-
# Stop and start adding new documentation elements to the current container.
|
548
|
-
# For example, if a class has a number of constants that you don't want to
|
549
|
-
# document, put a +:stopdoc:+ before the first, and a +:startdoc:+ after the
|
550
|
-
# last. If you don't specify a +:startdoc:+ by the end of the container,
|
551
|
-
# disables documentation for the rest of the current file.
|
552
|
-
#
|
553
|
-
# [+:doc:+]
|
554
|
-
# Forces a method or attribute to be documented even if it wouldn't be
|
555
|
-
# otherwise. Useful if, for example, you want to include documentation of a
|
556
|
-
# particular private method.
|
557
|
-
#
|
558
|
-
# [+:enddoc:+]
|
559
|
-
# Document nothing further at the current level: directives +:startdoc:+ and
|
560
|
-
# +:doc:+ that appear after this will not be honored for the current container
|
561
|
-
# (file, class or module), in the current file.
|
562
|
-
#
|
563
|
-
# [+:notnew:+ / +:not_new:+ / +:not-new:+ ]
|
564
|
-
# Only applicable to the +initialize+ instance method. Normally RDoc
|
565
|
-
# assumes that the documentation and parameters for +initialize+ are
|
566
|
-
# actually for the +new+ method, and so fakes out a +new+ for the class.
|
567
|
-
# The +:notnew:+ directive stops this. Remember that +initialize+ is private,
|
568
|
-
# so you won't see the documentation unless you use the +-a+ command line
|
569
|
-
# option.
|
570
|
-
#
|
571
|
-
# === Method arguments
|
572
|
-
#
|
573
|
-
# [+:arg:+ or +:args:+ _parameters_]
|
574
|
-
# Overrides the default argument handling with exactly these parameters.
|
575
|
-
#
|
576
|
-
# ##
|
577
|
-
# # :args: a, b
|
578
|
-
#
|
579
|
-
# def some_method(*a)
|
580
|
-
# end
|
581
|
-
#
|
582
|
-
# [+:yield:+ or +:yields:+ _parameters_]
|
583
|
-
# Overrides the default yield discovery with these parameters.
|
584
|
-
#
|
585
|
-
# ##
|
586
|
-
# # :yields: key, value
|
587
|
-
#
|
588
|
-
# def each_thing &block
|
589
|
-
# @things.each(&block)
|
590
|
-
# end
|
591
|
-
#
|
592
|
-
# [+:call-seq:+]
|
593
|
-
# Lines up to the next blank line or lines with a common prefix in the
|
594
|
-
# comment are treated as the method's calling sequence, overriding the
|
595
|
-
# default parsing of method parameters and yield arguments.
|
596
|
-
#
|
597
|
-
# Multiple lines may be used.
|
598
|
-
#
|
599
|
-
# # :call-seq:
|
600
|
-
# # ARGF.readlines(sep=$/) -> array
|
601
|
-
# # ARGF.readlines(limit) -> array
|
602
|
-
# # ARGF.readlines(sep, limit) -> array
|
603
|
-
# #
|
604
|
-
# # ARGF.to_a(sep=$/) -> array
|
605
|
-
# # ARGF.to_a(limit) -> array
|
606
|
-
# # ARGF.to_a(sep, limit) -> array
|
607
|
-
# #
|
608
|
-
# # The remaining lines are documentation ...
|
609
|
-
#
|
610
|
-
# === Sections
|
611
|
-
#
|
612
|
-
# Sections allow you to group methods in a class into sensible containers. If
|
613
|
-
# you use the sections 'Public', 'Internal' and 'Deprecated' (the three
|
614
|
-
# allowed method statuses from TomDoc) the sections will be displayed in that
|
615
|
-
# order placing the most useful methods at the top. Otherwise, sections will
|
616
|
-
# be displayed in alphabetical order.
|
617
|
-
#
|
618
|
-
# [+:category:+ _section_]
|
619
|
-
# Adds this item to the named +section+ overriding the current section. Use
|
620
|
-
# this to group methods by section in RDoc output while maintaining a
|
621
|
-
# sensible ordering (like alphabetical).
|
622
|
-
#
|
623
|
-
# # :category: Utility Methods
|
624
|
-
# #
|
625
|
-
# # CGI escapes +text+
|
626
|
-
#
|
627
|
-
# def convert_string text
|
628
|
-
# CGI.escapeHTML text
|
629
|
-
# end
|
630
|
-
#
|
631
|
-
# An empty category will place the item in the default category:
|
632
|
-
#
|
633
|
-
# # :category:
|
634
|
-
# #
|
635
|
-
# # This method is in the default category
|
636
|
-
#
|
637
|
-
# def some_method
|
638
|
-
# # ...
|
639
|
-
# end
|
640
|
-
#
|
641
|
-
# Unlike the :section: directive, :category: is not sticky. The category
|
642
|
-
# only applies to the item immediately following the comment.
|
643
|
-
#
|
644
|
-
# Use the :section: directive to provide introductory text for a section of
|
645
|
-
# documentation.
|
646
|
-
#
|
647
|
-
# [+:section:+ _title_]
|
648
|
-
# Provides section introductory text in RDoc output. The title following
|
649
|
-
# +:section:+ is used as the section name and the remainder of the comment
|
650
|
-
# containing the section is used as introductory text. A section's comment
|
651
|
-
# block must be separated from following comment blocks. Use an empty title
|
652
|
-
# to switch to the default section.
|
653
|
-
#
|
654
|
-
# The :section: directive is sticky, so subsequent methods, aliases,
|
655
|
-
# attributes, and classes will be contained in this section until the
|
656
|
-
# section is changed. The :category: directive will override the :section:
|
657
|
-
# directive.
|
658
|
-
#
|
659
|
-
# A :section: comment block may have one or more lines before the :section:
|
660
|
-
# directive. These will be removed, and any identical lines at the end of
|
661
|
-
# the block are also removed. This allows you to add visual cues to the
|
662
|
-
# section.
|
663
|
-
#
|
664
|
-
# Example:
|
665
|
-
#
|
666
|
-
# # ----------------------------------------
|
667
|
-
# # :section: My Section
|
668
|
-
# # This is the section that I wrote.
|
669
|
-
# # See it glisten in the noon-day sun.
|
670
|
-
# # ----------------------------------------
|
671
|
-
#
|
672
|
-
# ##
|
673
|
-
# # Comment for some_method
|
674
|
-
#
|
675
|
-
# def some_method
|
676
|
-
# # ...
|
677
|
-
# end
|
678
|
-
#
|
679
|
-
# === Other directives
|
680
|
-
#
|
681
|
-
# [+:markup:+ _type_]
|
682
|
-
# Overrides the default markup type for this comment with the specified
|
683
|
-
# markup type. For Ruby files, if the first comment contains this directive
|
684
|
-
# it is applied automatically to all comments in the file.
|
685
|
-
#
|
686
|
-
# Unless you are converting between markup formats you should use a
|
687
|
-
# <code>.rdoc_options</code> file to specify the default documentation
|
688
|
-
# format for your entire project. See RDoc::Options@Saved+Options for
|
689
|
-
# instructions.
|
690
|
-
#
|
691
|
-
# At the top of a file the +:markup:+ directive applies to the entire file:
|
692
|
-
#
|
693
|
-
# # coding: UTF-8
|
694
|
-
# # :markup: TomDoc
|
695
|
-
#
|
696
|
-
# # TomDoc comment here ...
|
697
|
-
#
|
698
|
-
# class MyClass
|
699
|
-
# # ...
|
700
|
-
#
|
701
|
-
# For just one comment:
|
702
|
-
#
|
703
|
-
# # ...
|
704
|
-
# end
|
705
|
-
#
|
706
|
-
# # :markup: RDoc
|
707
|
-
# #
|
708
|
-
# # This is a comment in RDoc markup format ...
|
709
|
-
#
|
710
|
-
# def some_method
|
711
|
-
# # ...
|
712
|
-
#
|
713
|
-
# See Markup@CONTRIBUTING for instructions on adding a new markup format.
|
714
|
-
#
|
715
|
-
# [+:include:+ _filename_]
|
716
|
-
# Include the contents of the named file at this point. This directive
|
717
|
-
# must appear alone on one line, possibly preceded by spaces. In this
|
718
|
-
# position, it can be escaped with a \ in front of the first colon.
|
719
|
-
#
|
720
|
-
# The file will be searched for in the directories listed by the +--include+
|
721
|
-
# option, or in the current directory by default. The contents of the file
|
722
|
-
# will be shifted to have the same indentation as the ':' at the start of
|
723
|
-
# the +:include:+ directive.
|
724
|
-
#
|
725
|
-
# [+:title:+ _text_]
|
726
|
-
# Sets the title for the document. Equivalent to the <tt>--title</tt>
|
727
|
-
# command line parameter. (The command line parameter overrides any :title:
|
728
|
-
# directive in the source).
|
729
|
-
#
|
730
|
-
# [+:main:+ _name_]
|
731
|
-
# Equivalent to the <tt>--main</tt> command line parameter.
|
100
|
+
# See RDoc::MarkupReference.
|
732
101
|
#
|
733
102
|
#--
|
734
103
|
# Original Author:: Dave Thomas, dave@pragmaticprogrammer.com
|
@@ -822,46 +191,45 @@ https://github.com/ruby/rdoc/issues
|
|
822
191
|
document.accept formatter
|
823
192
|
end
|
824
193
|
|
825
|
-
autoload :Parser,
|
826
|
-
autoload :PreProcess,
|
194
|
+
autoload :Parser, "#{__dir__}/markup/parser"
|
195
|
+
autoload :PreProcess, "#{__dir__}/markup/pre_process"
|
827
196
|
|
828
197
|
# Inline markup classes
|
829
|
-
autoload :AttrChanger,
|
830
|
-
autoload :AttrSpan,
|
831
|
-
autoload :Attributes,
|
832
|
-
autoload :AttributeManager,
|
833
|
-
autoload :RegexpHandling,
|
198
|
+
autoload :AttrChanger, "#{__dir__}/markup/attr_changer"
|
199
|
+
autoload :AttrSpan, "#{__dir__}/markup/attr_span"
|
200
|
+
autoload :Attributes, "#{__dir__}/markup/attributes"
|
201
|
+
autoload :AttributeManager, "#{__dir__}/markup/attribute_manager"
|
202
|
+
autoload :RegexpHandling, "#{__dir__}/markup/regexp_handling"
|
834
203
|
|
835
204
|
# RDoc::Markup AST
|
836
|
-
autoload :BlankLine,
|
837
|
-
autoload :BlockQuote,
|
838
|
-
autoload :Document,
|
839
|
-
autoload :HardBreak,
|
840
|
-
autoload :Heading,
|
841
|
-
autoload :Include,
|
842
|
-
autoload :IndentedParagraph,
|
843
|
-
autoload :List,
|
844
|
-
autoload :ListItem,
|
845
|
-
autoload :Paragraph,
|
846
|
-
autoload :Table,
|
847
|
-
autoload :Raw,
|
848
|
-
autoload :Rule,
|
849
|
-
autoload :Verbatim,
|
205
|
+
autoload :BlankLine, "#{__dir__}/markup/blank_line"
|
206
|
+
autoload :BlockQuote, "#{__dir__}/markup/block_quote"
|
207
|
+
autoload :Document, "#{__dir__}/markup/document"
|
208
|
+
autoload :HardBreak, "#{__dir__}/markup/hard_break"
|
209
|
+
autoload :Heading, "#{__dir__}/markup/heading"
|
210
|
+
autoload :Include, "#{__dir__}/markup/include"
|
211
|
+
autoload :IndentedParagraph, "#{__dir__}/markup/indented_paragraph"
|
212
|
+
autoload :List, "#{__dir__}/markup/list"
|
213
|
+
autoload :ListItem, "#{__dir__}/markup/list_item"
|
214
|
+
autoload :Paragraph, "#{__dir__}/markup/paragraph"
|
215
|
+
autoload :Table, "#{__dir__}/markup/table"
|
216
|
+
autoload :Raw, "#{__dir__}/markup/raw"
|
217
|
+
autoload :Rule, "#{__dir__}/markup/rule"
|
218
|
+
autoload :Verbatim, "#{__dir__}/markup/verbatim"
|
850
219
|
|
851
220
|
# Formatters
|
852
|
-
autoload :Formatter,
|
853
|
-
|
854
|
-
autoload :ToAnsi,
|
855
|
-
autoload :ToBs,
|
856
|
-
autoload :ToHtml,
|
857
|
-
autoload :ToHtmlCrossref,
|
858
|
-
autoload :ToHtmlSnippet,
|
859
|
-
autoload :ToLabel,
|
860
|
-
autoload :ToMarkdown,
|
861
|
-
autoload :ToRdoc,
|
862
|
-
autoload :ToTableOfContents,
|
863
|
-
autoload :ToTest,
|
864
|
-
autoload :ToTtOnly,
|
221
|
+
autoload :Formatter, "#{__dir__}/markup/formatter"
|
222
|
+
|
223
|
+
autoload :ToAnsi, "#{__dir__}/markup/to_ansi"
|
224
|
+
autoload :ToBs, "#{__dir__}/markup/to_bs"
|
225
|
+
autoload :ToHtml, "#{__dir__}/markup/to_html"
|
226
|
+
autoload :ToHtmlCrossref, "#{__dir__}/markup/to_html_crossref"
|
227
|
+
autoload :ToHtmlSnippet, "#{__dir__}/markup/to_html_snippet"
|
228
|
+
autoload :ToLabel, "#{__dir__}/markup/to_label"
|
229
|
+
autoload :ToMarkdown, "#{__dir__}/markup/to_markdown"
|
230
|
+
autoload :ToRdoc, "#{__dir__}/markup/to_rdoc"
|
231
|
+
autoload :ToTableOfContents, "#{__dir__}/markup/to_table_of_contents"
|
232
|
+
autoload :ToTest, "#{__dir__}/markup/to_test"
|
233
|
+
autoload :ToTtOnly, "#{__dir__}/markup/to_tt_only"
|
865
234
|
|
866
235
|
end
|
867
|
-
|