RubyGems - rdoc - Versions diffs - 2.5.11 → 3.0 - Mend

rdoc 2.5.11 → 3.0

Potentially problematic release.

This version of rdoc might be problematic. Click here for more details.

Files changed (113) hide show

data.tar.gz.sig +0 -0
data/.document +1 -0
data/History.txt +95 -0
data/Manifest.txt +13 -4
data/README.txt +9 -3
data/Rakefile +1 -1
data/lib/rdoc.rb +15 -298
data/lib/rdoc/alias.rb +65 -16
data/lib/rdoc/any_method.rb +27 -150
data/lib/rdoc/attr.rb +36 -115
data/lib/rdoc/class_module.rb +236 -22
data/lib/rdoc/code_object.rb +76 -31
data/lib/rdoc/constant.rb +32 -4
data/lib/rdoc/context.rb +494 -222
data/lib/rdoc/encoding.rb +79 -0
data/lib/rdoc/erbio.rb +37 -0
data/lib/rdoc/gauntlet.rb +9 -5
data/lib/rdoc/generator.rb +33 -1
data/lib/rdoc/generator/darkfish.rb +284 -375
data/lib/rdoc/generator/markup.rb +72 -36
data/lib/rdoc/generator/ri.rb +4 -4
data/lib/rdoc/generator/template/darkfish/classpage.rhtml +267 -274
data/lib/rdoc/generator/template/darkfish/filepage.rhtml +91 -91
data/lib/rdoc/generator/template/darkfish/index.rhtml +45 -45
data/lib/rdoc/generator/template/darkfish/rdoc.css +298 -298
data/lib/rdoc/include.rb +40 -1
data/lib/rdoc/known_classes.rb +1 -0
data/lib/rdoc/markup.rb +467 -2
data/lib/rdoc/markup/attribute_manager.rb +24 -6
data/lib/rdoc/markup/blank_line.rb +11 -3
data/lib/rdoc/markup/document.rb +6 -0
data/lib/rdoc/markup/formatter.rb +10 -0
data/lib/rdoc/markup/formatter_test_case.rb +339 -3
data/lib/rdoc/markup/heading.rb +3 -0
data/lib/rdoc/markup/inline.rb +11 -1
data/lib/rdoc/markup/list.rb +3 -0
data/lib/rdoc/markup/list_item.rb +3 -0
data/lib/rdoc/markup/paragraph.rb +3 -0
data/lib/rdoc/markup/parser.rb +191 -237
data/lib/rdoc/markup/{preprocess.rb → pre_process.rb} +50 -29
data/lib/rdoc/markup/raw.rb +4 -0
data/lib/rdoc/markup/rule.rb +3 -0
data/lib/rdoc/markup/text_formatter_test_case.rb +116 -0
data/lib/rdoc/markup/to_ansi.rb +14 -2
data/lib/rdoc/markup/to_bs.rb +8 -2
data/lib/rdoc/markup/to_html.rb +84 -91
data/lib/rdoc/markup/to_html_crossref.rb +77 -26
data/lib/rdoc/markup/to_rdoc.rb +94 -49
data/lib/rdoc/markup/to_test.rb +9 -1
data/lib/rdoc/markup/verbatim.rb +6 -3
data/lib/rdoc/method_attr.rb +353 -0
data/lib/rdoc/normal_class.rb +11 -2
data/lib/rdoc/normal_module.rb +0 -5
data/lib/rdoc/options.rb +373 -82
data/lib/rdoc/parser.rb +59 -23
data/lib/rdoc/parser/c.rb +224 -86
data/lib/rdoc/parser/ruby.rb +219 -111
data/lib/rdoc/parser/ruby_tools.rb +4 -1
data/lib/rdoc/parser/simple.rb +9 -4
data/lib/rdoc/rdoc.rb +68 -28
data/lib/rdoc/require.rb +21 -0
data/lib/rdoc/ri/driver.rb +20 -10
data/lib/rdoc/ri/paths.rb +2 -2
data/lib/rdoc/ri/store.rb +22 -5
data/lib/rdoc/ruby_lex.rb +11 -12
data/lib/rdoc/ruby_token.rb +2 -2
data/lib/rdoc/single_class.rb +2 -1
data/lib/rdoc/stats.rb +202 -162
data/lib/rdoc/stats/normal.rb +51 -0
data/lib/rdoc/stats/quiet.rb +59 -0
data/lib/rdoc/stats/verbose.rb +45 -0
data/lib/rdoc/text.rb +133 -4
data/lib/rdoc/{tokenstream.rb → token_stream.rb} +0 -2
data/lib/rdoc/top_level.rb +230 -39
data/test/test_attribute_manager.rb +58 -7
data/test/test_rdoc_alias.rb +13 -0
data/test/test_rdoc_any_method.rb +43 -2
data/test/test_rdoc_attr.rb +15 -8
data/test/test_rdoc_class_module.rb +133 -0
data/test/test_rdoc_code_object.rb +62 -5
data/test/test_rdoc_context.rb +72 -26
data/test/test_rdoc_encoding.rb +145 -0
data/test/test_rdoc_generator_darkfish.rb +119 -0
data/test/test_rdoc_generator_ri.rb +22 -2
data/test/test_rdoc_include.rb +79 -0
data/test/test_rdoc_markup_attribute_manager.rb +4 -4
data/test/test_rdoc_markup_parser.rb +134 -95
data/test/test_rdoc_markup_pre_process.rb +7 -2
data/test/test_rdoc_markup_to_ansi.rb +43 -153
data/test/test_rdoc_markup_to_bs.rb +42 -156
data/test/test_rdoc_markup_to_html.rb +130 -58
data/test/test_rdoc_markup_to_html_crossref.rb +10 -10
data/test/test_rdoc_markup_to_rdoc.rb +40 -151
data/test/test_rdoc_method_attr.rb +122 -0
data/test/test_rdoc_normal_class.rb +1 -1
data/test/test_rdoc_normal_module.rb +6 -1
data/test/test_rdoc_options.rb +237 -12
data/test/test_rdoc_parser.rb +3 -22
data/test/test_rdoc_parser_c.rb +203 -2
data/test/test_rdoc_parser_ruby.rb +403 -89
data/test/test_rdoc_parser_simple.rb +25 -1
data/test/test_rdoc_rdoc.rb +44 -32
data/test/test_rdoc_ri_driver.rb +29 -24
data/test/test_rdoc_ri_store.rb +46 -3
data/test/test_rdoc_task.rb +1 -1
data/test/test_rdoc_text.rb +102 -8
data/test/test_rdoc_top_level.rb +13 -4
data/test/xref_data.rb +8 -0
data/test/xref_test_case.rb +6 -0
metadata +29 -19
metadata.gz.sig +0 -0
data/lib/rdoc/parser/perl.rb +0 -165
data/test/test_rdoc_parser_perl.rb +0 -73

@@ -17,6 +17,7 @@ class RDoc::Include < RDoc::CodeObject
     super()
     @name = name
     self.comment = comment
+    @module = nil   # cache for module if found
   end
   ##
@@ -52,9 +53,47 @@ class RDoc::Include < RDoc::CodeObject
   ##
   # Attempts to locate the included module object.  Returns the name if not
   # known.
+  #
+  # The scoping rules of Ruby to resolve the name of an included module are:
+  # - first look into the children of the current context;
+  # - if not found, look into the children of included modules,
+  #   in reverse inclusion order;
+  # - if still not found, go up the hierarchy of names.
   def module
-    RDoc::TopLevel.find_module_named(@name) || @name
+    return @module if @module
+    # search the current context
+    return @name unless parent
+    full_name = parent.child_name(@name)
+    @module = RDoc::TopLevel.modules_hash[full_name]
+    return @module if @module
+    return @name if @name =~ /^::/
+    # search the includes before this one, in reverse order
+    searched = parent.includes.take_while { |i| i != self }.reverse
+    searched.each do |i|
+      inc = i.module
+      next if String === inc
+      full_name = inc.child_name(@name)
+      @module = RDoc::TopLevel.modules_hash[full_name]
+      return @module if @module
+    end
+    # go up the hierarchy of names
+    p = parent.parent
+    while p
+      full_name = p.child_name(@name)
+      @module = RDoc::TopLevel.modules_hash[full_name]
+      return @module if @module
+      p = p.parent
+    end
+    @name
+  end
+  def to_s # :nodoc:
+    "include #@name in: #{parent}"
   end
 end

data/lib/rdoc/known_classes.rb CHANGED

@@ -10,6 +10,7 @@ module RDoc
     "rb_cClass"            => "Class",
     "rb_cData"             => "Data",
     "rb_cDir"              => "Dir",
+    "rb_cEncoding"         => "Encoding",
     "rb_cFalseClass"       => "FalseClass",
     "rb_cFile"             => "File",
     "rb_cFixnum"           => "Fixnum",

data/lib/rdoc/markup.rb CHANGED

@@ -59,12 +59,477 @@ require 'rdoc'
 #
 #   puts "<body>#{wh.convert ARGF.read}</body>"
 #
+# == Encoding
+#
+# Where Encoding support is available RDoc will automatically convert all
+# documents to the same output encoding.  The output encoding can be set via
+# RDoc::Options#encoding and defaults to Encoding.default_external.
+#
+# = \RDoc Markup Reference
+#
+# == Block Markup
+#
+# === Paragraphs and Verbatim
+#
+# The markup engine looks for a document's natural left margin.  This is
+# used as the initial margin for the document.
+#
+# Consecutive lines starting at this margin are considered to be a
+# paragraph. Empty lines separate paragraphs.
+#
+# Any line that starts to the right of the current margin is treated
+# as verbatim text.  This is useful for code listings:
+#
+#   3.times { puts "Ruby" }
+#
+# In verbatim text, two or more blank lines are collapsed into one,
+# and trailing blank lines are removed:
+#
+#   This is the first line
+#
+#
+#   This is the second non-blank line,
+#   after 2 blank lines in the source markup.
+#
+#
+# There were two trailing blank lines right above this paragraph, that
+# have been removed. In addition, the verbatim text has been shifted
+# left, so the amount of indentation of verbatim text is unimportant.
+#
+# === Headers and Rules
+#
+# A line starting with an equal sign (=) is treated as a
+# heading.  Level one headings have one equals sign, level two headings
+# have two, and so on until level six, which is the maximum
+# (seven hyphens or more result in a level six heading).
+#
+# For example, the above header was obtained with:
+#   == Headers and Rules
+#
+# A line starting with three or more hyphens (at the current indent)
+# generates a horizontal rule.  The more hyphens, the thicker the rule
+# (within reason, and if supported by the output device).
+#
+# In the case of HTML output, three dashes generate a 1-pixel high rule,
+# four dashes result in 2 pixels, and so on. The actual height is limited
+# to 10 pixels:
+#
+#   ---
+#   -----
+#   -----------------------------------------------------
+#
+# produces:
+#
+# ---
+# -----
+# -----------------------------------------------------
+#
+# === Simple Lists
+#
+# If a paragraph starts with a "*", "-", "<digit>." or "<letter>.",
+# then it is taken to be the start of a list.  The margin in increased to be
+# the first non-space following the list start flag.  Subsequent lines
+# should be indented to this new margin until the list ends.  For example:
+#
+#   * this is a list with three paragraphs in
+#     the first item.  This is the first paragraph.
+#
+#     And this is the second paragraph.
+#
+#     1. This is an indented, numbered list.
+#     2. This is the second item in that list
+#
+#     This is the third conventional paragraph in the
+#     first list item.
+#
+#   * This is the second item in the original list
+#
+# produces:
+#
+# * this is a list with three paragraphs in
+#   the first item.  This is the first paragraph.
+#
+#   And this is the second paragraph.
+#
+#   1. This is an indented, numbered list.
+#   2. This is the second item in that list
+#
+#   This is the third conventional paragraph in the
+#   first list item.
+#
+# * This is the second item in the original list
+#
+# === Labeled Lists
+#
+# You can also construct labeled lists, sometimes called description
+# or definition lists.  Do this by putting the label in square brackets
+# and indenting the list body:
+#
+#   [cat]  a small furry mammal
+#          that seems to sleep a lot
+#
+#   [ant]  a little insect that is known
+#          to enjoy picnics
+#
+# produces:
+#
+# [cat]  a small furry mammal
+#        that seems to sleep a lot
+#
+# [ant]  a little insect that is known
+#        to enjoy picnics
+#
+# If you want the list bodies to line up to the left of the labels,
+# use two colons:
+#
+#   cat::  a small furry mammal
+#          that seems to sleep a lot
+#
+#   ant::  a little insect that is known
+#          to enjoy picnics
+#
+# produces:
+#
+# cat::  a small furry mammal
+#        that seems to sleep a lot
+#
+# ant::  a little insect that is known
+#        to enjoy picnics
+#
+# Notice that blank lines right after the label are ignored in labeled lists:
+#
+#   [one]
+#
+#       definition 1
+#
+#   [two]
+#
+#       definition 2
+#
+# produces the same output as
+#
+#   [one]  definition 1
+#   [two]  definition 2
+#
+#
+# === Lists and Verbatim
+#
+# If you want to introduce a verbatim section right after a list, it has to be
+# less indented than the list item bodies, but more indented than the list
+# label, letter, digit or bullet. For instance:
+#
+#   *   point 1
+#
+#   *   point 2, first paragraph
+#
+#       point 2, second paragraph
+#         verbatim text inside point 2
+#       point 2, third paragraph
+#     verbatim text outside of the list (the list is therefore closed)
+#   regular paragraph after the list
+#
+# produces:
+#
+# *   point 1
+#
+# *   point 2, first paragraph
+#
+#     point 2, second paragraph
+#       verbatim text inside point 2
+#     point 2, third paragraph
+#   verbatim text outside of the list (the list is therefore closed)
+# regular paragraph after the list
+#
+#
+# == Text Markup
+#
+# === Bold, Italic, Typewriter Text
+#
+# You can use markup within text (except verbatim) to change the
+# appearance of parts of that text.  Out of the box, RDoc::Markup
+# supports word-based and general markup.
+#
+# Word-based markup uses flag characters around individual words:
+#
+# <tt>\*_word_\*</tt>::  displays _word_ in a *bold* font
+# <tt>\__word_\_</tt>::  displays _word_ in an _emphasized_ font
+# <tt>\+_word_\+</tt>::  displays _word_ in a +code+ font
+#
+# General markup affects text between a start delimiter and an end
+# delimiter.  Not surprisingly, these delimiters look like HTML markup.
+#
+# <tt>\<b>_text_</b></tt>::    displays _text_ in a *bold* font
+# <tt>\<em>_text_</em></tt>::  displays _text_ in an _emphasized_ font
+#                              (alternate tag: <tt>\<i></tt>)
+# <tt>\<tt>_text_\</tt></tt>:: displays _text_ in a +code+ font
+#                              (alternate tag: <tt>\<code></tt>)
+#
+# Unlike conventional Wiki markup, general markup can cross line
+# boundaries.  You can turn off the interpretation of markup by
+# preceding the first character with a backslash (see <i>Escaping
+# Text Markup</i>, below).
+#
+# === Hyperlinks
+#
+# Hyperlinks to the web starting with +http:+, +mailto:+, +ftp:+ or +www.+
+# are recognized.  An HTTP url that references an external image file is
+# converted into an inline <img...>.  Hyperlinks starting with +link:+ are
+# assumed to refer to local files whose path is relative to the <tt>--op</tt>
+# directory.
+#
+# Hyperlinks can also be of the form _label_[_url_], in which
+# case _label_ is used in the displayed text, and _url_ is
+# used as the target.  If _label_ contains multiple words,
+# put it in braces: {<em>multi word label</em>}[url].
+#
+# Example hyperlinks:
+#
+#   link:RDoc.html
+#   http://rdoc.rubyforge.org
+#   mailto:user@example.com
+#   {RDoc Documentation}[http://rdoc.rubyforge.org]
+#   {RDoc Markup}[link:RDoc/Markup.html]
+#
+# === Escaping Text Markup
+#
+# Text markup can be escaped with a backslash, as in \<tt>, which was obtained
+# with "<tt>\\<tt></tt>". Except in verbatim sections and between \<tt> tags,
+# to produce a backslash, you have to double it unless it is followed by a
+# space, tab or newline. Otherwise, the HTML formatter will discard it, as it
+# is used to escape potential hyperlinks:
+#
+#   * The \ must be doubled if not followed by white space: \\.
+#   * But not in \<tt> tags: in a Regexp, <tt>\S</tt> matches non-space.
+#   * This is a link to {ruby-lang}[www.ruby-lang.org].
+#   * This is not a link, however: \{ruby-lang.org}[www.ruby-lang.org].
+#   * This will not be hyperlinked to \RDoc::RDoc#document
+#
+# generates:
+#
+# * The \ must be doubled if not followed by white space: \\.
+# * But not in \<tt> tags: in a Regexp, <tt>\S</tt> matches non-space.
+# * This is a link to {ruby-lang}[www.ruby-lang.org]
+# * This is not a link, however: \{ruby-lang.org}[www.ruby-lang.org]
+# * This will not be hyperlinked to \RDoc::RDoc#document
+#
+# Inside \<tt> tags, more precisely, leading backslashes are removed
+# only if followed by a markup character (<tt><*_+</tt>), a backslash,
+# or a known hyperlink reference (a known class or method). So in the
+# example above, the backslash of <tt>\S</tt> would be removed
+# if there was a class or module named +S+ in the current context.
+#
+# This behavior is inherited from RDoc version 1, and has been kept
+# for compatibility with existing RDoc documentation.
+#
+# === Conversion of characters
+#
+# HTML will convert two/three dashes to an em-dash. Other common characters are
+# converted as well:
+#
+#   em-dash::  -- or ---
+#   ellipsis:: ...
+#
+#   single quotes:: 'text' or `text'
+#   double quotes:: "text" or ``text''
+#
+#   copyright:: (c)
+#   registered trademark:: (r)
+#
+# produces:
+#
+# em-dash::  -- or ---
+# ellipsis:: ...
+#
+# single quotes:: 'text' or `text'
+# double quotes:: "text" or ``text''
+#
+# copyright:: (c)
+# registered trademark:: (r)
+#
+#
+# == Documenting Source Code
+#
+# Comment blocks can be written fairly naturally, either using <tt>#</tt> on
+# successive lines of the comment, or by including the comment in
+# a <tt>=begin</tt>/<tt>=end</tt> block.  If you use the latter form,
+# the <tt>=begin</tt> line _must_ be flagged with an +rdoc+ tag:
+#
+#   =begin rdoc
+#   Documentation to be processed by RDoc.
+#
+#   ...
+#   =end
+#
+# RDoc stops processing comments if it finds a comment line starting
+# with <tt>--</tt> right after the <tt>#</tt> character (otherwise,
+# it will be treated as a rule if it has three dashes or more).
+# This can be used to separate external from internal comments,
+# or to stop a comment being associated with a method, class, or module.
+# Commenting can be turned back on with a line that starts with <tt>++</tt>.
+#
+#   ##
+#   # Extract the age and calculate the date-of-birth.
+#   #--
+#   # FIXME: fails if the birthday falls on February 29th
+#   #++
+#   # The DOB is returned as a Time object.
+#
+#   def get_dob(person)
+#     # ...
+#   end
+#
+# Names of classes, files, and any method names containing an
+# underscore or preceded by a hash character are automatically hyperlinked
+# from comment text to their description. This hyperlinking works inside
+# the current class or module, and with ancestor methods (in included modules
+# or in the superclass).
+#
+# Method parameter lists are extracted and displayed with the method
+# description.  If a method calls +yield+, then the parameters passed to yield
+# will also be displayed:
+#
+#   def fred
+#     ...
+#     yield line, address
+#
+# This will get documented as:
+#
+#   fred() { |line, address| ... }
+#
+# You can override this using a comment containing ':yields: ...' immediately
+# after the method definition
+#
+#   def fred # :yields: index, position
+#     # ...
+#
+#     yield line, address
+#
+# which will get documented as
+#
+#    fred() { |index, position| ... }
+#
+# +:yields:+ is an example of a documentation directive.  These appear
+# immediately after the start of the document element they are modifying.
+#
+# RDoc automatically cross-references words with underscores or camel-case.
+# To suppress cross-references, prefix the word with a \ character.  To
+# include special characters like "<tt>\n</tt>", you'll need to use
+# two \ characters in normal text, but only one in \<tt> text:
+#
+#   "\\n" or "<tt>\n</tt>"
+#
+# produces:
+#
+# "\\n" or "<tt>\n</tt>"
+#
+# == Directives
+#
+# Directives are keywords surrounded by ":" characters.
+#
+# === Controlling what is documented
+#
+# [+:nodoc:+ / <tt>:nodoc: all</tt>]
+#   This directive prevents documentation for the element from
+#   being generated.  For classes and modules, the methods, aliases,
+#   constants, and attributes directly within the affected class or
+#   module also will be omitted.  By default, though, modules and
+#   classes within that class of module _will_ be documented.  This is
+#   turned off by adding the +all+ modifier.
+#
+#     module MyModule # :nodoc:
+#       class Input
+#       end
+#     end
+#
+#     module OtherModule # :nodoc: all
+#       class Output
+#       end
+#     end
+#
+#   In the above code, only class <tt>MyModule::Input</tt> will be documented.
+#
+#   The +:nodoc:+ directive, like +:enddoc:+, +:stopdoc:+ and +:startdoc:+
+#   presented below, is local to the current file: if you do not want to
+#   document a module that appears in several files, specify +:nodoc:+ on each
+#   appearance, at least once per file.
+#
+# [+:stopdoc:+ / +:startdoc:+]
+#   Stop and start adding new documentation elements to the current container.
+#   For example, if a class has a number of constants that you don't want to
+#   document, put a +:stopdoc:+ before the first, and a +:startdoc:+ after the
+#   last.  If you don't specify a +:startdoc:+ by the end of the container,
+#   disables documentation for the rest of the current file.
+#
+# [+:doc:+]
+#   Forces a method or attribute to be documented even if it wouldn't be
+#   otherwise.  Useful if, for example, you want to include documentation of a
+#   particular private method.
+#
+# [+:enddoc:+]
+#   Document nothing further at the current level: directives +:startdoc:+ and
+#   +:doc:+ that appear after this will not be honored for the current container
+#   (file, class or module), in the current file.
+#
+# [+:notnew:+ / +:not_new:+ / +:not-new:+ ]
+#   Only applicable to the +initialize+ instance method.  Normally RDoc
+#   assumes that the documentation and parameters for +initialize+ are
+#   actually for the +new+ method, and so fakes out a +new+ for the class.
+#   The +:notnew:+ directive stops this.  Remember that +initialize+ is private,
+#   so you won't see the documentation unless you use the +-a+ command line
+#   option.
+#
+# === Other directives
+#
+# [+:include:+ _filename_]
+#   Include the contents of the named file at this point. This directive
+#   must appear alone on one line, possibly preceded by spaces. In this
+#   position, it can be escapd with a \ in front of the first colon.
+#
+#   The file will be searched for in the directories listed by the +--include+
+#   option, or in the current directory by default.  The contents of the file
+#   will be shifted to have the same indentation as the ':' at the start of
+#   the +:include:+ directive.
+#
+# [+:title:+ _text_]
+#   Sets the title for the document.  Equivalent to the <tt>--title</tt>
+#   command line parameter.  (The command line parameter overrides any :title:
+#   directive in the source).
+#
+# [+:main:+ _name_]
+#   Equivalent to the <tt>--main</tt> command line parameter.
+#
+# [<tt>:section: title</tt>]
+#   Starts a new section in the output.  The title following +:section:+ is
+#   used as the section heading, and the remainder of the comment containing
+#   the section is used as introductory text.  Subsequent methods, aliases,
+#   attributes, and classes will be documented in this section.  A :section:
+#   comment block may have one or more lines before the :section: directive.
+#   These will be removed, and any identical lines at the end of the block are
+#   also removed.  This allows you to add visual cues such as:
+#
+#     # ----------------------------------------
+#     # :section: My Section
+#     # This is the section that I wrote.
+#     # See it glisten in the noon-day sun.
+#     # ----------------------------------------
+#
+#   <i>Note: Current formatters to not take sections into account.</i>
+#
+# [+:call-seq:+]
+#   Lines up to the next blank line in the comment are treated as the method's
+#   calling sequence, overriding the default parsing of method parameters and
+#   yield arguments.
+#
+# Further directives can be found in RDoc::Parser::Ruby and RDoc::Parser::C.
 #--
-# Author::   Dave Thomas,  dave@pragmaticprogrammer.com
-# License::  Ruby license
+# Original Author:: Dave Thomas,  dave@pragmaticprogrammer.com
+# License:: Ruby license
 class RDoc::Markup
+  ##
+  # An AttributeManager which handles inline markup.
   attr_reader :attribute_manager
   ##