ruby-changes:20719
From: drbrain <ko1@a...>
Date: Sun, 31 Jul 2011 09:19:19 +0900 (JST)
Subject: [ruby-changes:20719] drbrain:r32767 (trunk): * lib/rdoc: Update to RDoc 3.9. Fixed `ri []`, stopdoc creating an
drbrain 2011-07-31 09:19:00 +0900 (Sun, 31 Jul 2011) New Revision: 32767 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=32767 Log: * lib/rdoc: Update to RDoc 3.9. Fixed `ri []`, stopdoc creating an object reference, nodoc for class aliases, verbatim === lines. Added files: trunk/lib/rdoc/cross_reference.rb trunk/test/rdoc/test_rdoc_cross_reference.rb Modified files: trunk/ChangeLog trunk/bin/rdoc trunk/bin/ri trunk/lib/rdoc/class_module.rb trunk/lib/rdoc/code_object.rb trunk/lib/rdoc/context.rb trunk/lib/rdoc/generator/darkfish.rb trunk/lib/rdoc/generator/template/darkfish/classpage.rhtml trunk/lib/rdoc/markup/document.rb trunk/lib/rdoc/markup/formatter.rb trunk/lib/rdoc/markup/parser.rb trunk/lib/rdoc/markup/pre_process.rb trunk/lib/rdoc/markup/to_html.rb trunk/lib/rdoc/markup/to_html_crossref.rb trunk/lib/rdoc/markup.rb trunk/lib/rdoc/parser/c.rb trunk/lib/rdoc/parser/ruby.rb trunk/lib/rdoc/parser/ruby_tools.rb trunk/lib/rdoc/parser.rb trunk/lib/rdoc/ri/driver.rb trunk/lib/rdoc.rb trunk/test/rdoc/test_rdoc_code_object.rb trunk/test/rdoc/test_rdoc_generator_darkfish.rb trunk/test/rdoc/test_rdoc_markup_document.rb trunk/test/rdoc/test_rdoc_markup_parser.rb trunk/test/rdoc/test_rdoc_markup_pre_process.rb trunk/test/rdoc/test_rdoc_markup_to_html.rb trunk/test/rdoc/test_rdoc_markup_to_html_crossref.rb trunk/test/rdoc/test_rdoc_parser_ruby.rb trunk/test/rdoc/test_rdoc_ri_driver.rb trunk/test/rdoc/xref_test_case.rb Index: ChangeLog =================================================================== --- ChangeLog (revision 32766) +++ ChangeLog (revision 32767) @@ -1,3 +1,8 @@ +Sun Jul 31 09:18:28 2011 Eric Hodel <drbrain@s...> + + * lib/rdoc: Update to RDoc 3.9. Fixed `ri []`, stopdoc creating an + object reference, nodoc for class aliases, verbatim === lines. + Sun Jul 31 01:29:08 2011 NARUSE, Yui <naruse@r...> * io.c (rb_io_each_byte): remove unused variable e. Index: lib/rdoc.rb =================================================================== --- lib/rdoc.rb (revision 32766) +++ lib/rdoc.rb (revision 32767) @@ -104,7 +104,7 @@ ## # RDoc version you are using - VERSION = '3.8' + VERSION = '3.9' ## # Method visibilities Index: lib/rdoc/context.rb =================================================================== --- lib/rdoc/context.rb (revision 32766) +++ lib/rdoc/context.rb (revision 32767) @@ -423,6 +423,7 @@ if klass then # if TopLevel, it may not be registered in the classes: enclosing.classes_hash[name] = klass + # update the superclass if needed if superclass then existing = klass.superclass @@ -623,8 +624,10 @@ ## # Is there any content? - # This means any of: comment, aliases, methods, attributes, - # external aliases, require, constant. + # + # This means any of: comment, aliases, methods, attributes, external + # aliases, require, constant. + # # Includes are also checked unless <tt>includes == false</tt>. def any_content(includes = true) Index: lib/rdoc/generator/template/darkfish/classpage.rhtml =================================================================== --- lib/rdoc/generator/template/darkfish/classpage.rhtml (revision 32766) +++ lib/rdoc/generator/template/darkfish/classpage.rhtml (revision 32767) @@ -176,6 +176,8 @@ </div><!-- description --> <% klass.each_section do |section, constants, attributes| %> + <% constants = constants.select { |const| const.display? } %> + <% attributes = attributes.select { |attr| attr.display? } %> <div id="<%= section.aref %>" class="documentation-section"> <% if section.title then %> <h2 class="section-header"> Index: lib/rdoc/generator/darkfish.rb =================================================================== --- lib/rdoc/generator/darkfish.rb (revision 32766) +++ lib/rdoc/generator/darkfish.rb (revision 32767) @@ -192,7 +192,7 @@ top_level = klass.full_name.gsub( /::.*/, '' ) [nscounts[top_level] * -1, klass.full_name] end.select do |klass| - klass.document_self + klass.display? end end Index: lib/rdoc/parser.rb =================================================================== --- lib/rdoc/parser.rb (revision 32766) +++ lib/rdoc/parser.rb (revision 32767) @@ -106,6 +106,8 @@ # Applies +directive+'s +value+ to +code_object+, if appropriate def self.process_directive code_object, directive, value + warn "RDoc::Parser::process_directive is deprecated and wil be removed in RDoc 4. Use RDoc::Markup::PreProcess#handle_directive instead" if $-w + case directive when 'nodoc' then code_object.document_self = nil # notify nodoc @@ -196,6 +198,9 @@ @content = content @options = options @stats = stats + + @preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include + @preprocess.options = @options end end Index: lib/rdoc/markup/document.rb =================================================================== --- lib/rdoc/markup/document.rb (revision 32766) +++ lib/rdoc/markup/document.rb (revision 32767) @@ -71,9 +71,7 @@ # Does this document have no parts? def empty? - @parts.empty? or - (@parts.length == 1 and RDoc::Markup::Document === @parts.first and - @parts.first.empty?) + @parts.empty? or (@parts.length == 1 and merged? and @parts.first.empty?) end ## @@ -85,6 +83,11 @@ # The information in +other+ is preferred over the receiver def merge other + if empty? then + @parts = other.parts + return self + end + other.parts.each do |other_part| self.parts.delete_if do |self_part| self_part.file and self_part.file == other_part.file @@ -96,6 +99,13 @@ self end + ## + # Does this Document contain other Documents? + + def merged? + RDoc::Markup::Document === @parts.first + end + def pretty_print q # :nodoc: start = @file ? "[doc (#{@file}): " : '[doc: ' Index: lib/rdoc/markup/pre_process.rb =================================================================== --- lib/rdoc/markup/pre_process.rb (revision 32766) +++ lib/rdoc/markup/pre_process.rb (revision 32767) @@ -13,6 +13,8 @@ class RDoc::Markup::PreProcess + attr_accessor :options + @registered = {} ## @@ -38,6 +40,7 @@ def initialize(input_file_name, include_path) @input_file_name = input_file_name @include_path = include_path + @options = nil end ## @@ -54,54 +57,120 @@ # If +code_object+ is given and the param is set as metadata on the # +code_object+. See RDoc::CodeObject#metadata - def handle text, code_object = nil + def handle text, code_object = nil, &block + encoding = if defined?(Encoding) then text.encoding else nil end # regexp helper (square brackets for optional) # $1 $2 $3 $4 $5 # [prefix][\]:directive:[spaces][param]newline - text.gsub!(/^([ \t]*#?[ \t]*)(\\?):(\w+):([ \t]*)(.+)?\n/) do + text.gsub!(/^([ \t]*(?:#|\/?\*)?[ \t]*)(\\?):(\w+):([ \t]*)(.+)?\n/) do # skip something like ':toto::' next $& if $4.empty? and $5 and $5[0, 1] == ':' # skip if escaped next "#$1:#$3:#$4#$5\n" unless $2.empty? - prefix = $1 - directive = $3.downcase - param = $5 + handle_directive $1, $3, $5, code_object, encoding, &block + end - case directive - when 'include' then - filename = param.split[0] - encoding = if defined?(Encoding) then text.encoding else nil end - include_file filename, prefix, encoding - when 'category' then - if RDoc::Context === code_object then - section = code_object.add_section param, '' - code_object.temporary_section = section - end + text + end - '' # ignore category if we're not on an RDoc::Context - else - result = yield directive, param if block_given? + #-- + # When 1.8.7 support is ditched prefix can be defaulted to '' - case result - when nil then - code_object.metadata[directive] = param if code_object - if RDoc::Markup::PreProcess.registered.include? directive then - handler = RDoc::Markup::PreProcess.registered[directive] - result = handler.call directive, param if handler - else - result = "#{prefix}:#{directive}: #{param}\n" - end - when false then + def handle_directive prefix, directive, param, code_object = nil, + encoding = nil + blankline = "#{prefix.strip}\n" + directive = directive.downcase + + case directive + when 'arg', 'args' then + return blankline unless code_object + + code_object.params = param + + blankline + when 'category' then + if RDoc::Context === code_object then + section = code_object.add_section param, '' + code_object.temporary_section = section + end + + blankline # ignore category if we're not on an RDoc::Context + when 'doc' then + return blankline unless code_object + code_object.document_self = true + code_object.force_documentation = true + + blankline + when 'enddoc' then + return blankline unless code_object + code_object.done_documenting = true + + blankline + when 'include' then + filename = param.split.first + include_file filename, prefix, encoding + when 'main' then + @options.main_page = param if @options.respond_to? :main_page + + blankline + when 'nodoc' then + return blankline unless code_object + code_object.document_self = nil # notify nodoc + code_object.document_children = param !~ /all/i + + blankline + when 'notnew', 'not_new', 'not-new' then + return blankline unless RDoc::AnyMethod === code_object + + code_object.dont_rename_initialize = true + + blankline + when 'startdoc' then + return blankline unless code_object + + code_object.start_doc + code_object.force_documentation = true + + blankline + when 'stopdoc' then + return blankline unless code_object + + code_object.stop_doc + + blankline + when 'title' then + @options.default_title = param if @options.respond_to? :default_title= + + blankline + when 'yield', 'yields' then + return blankline unless code_object + # remove parameter &block + code_object.params.sub!(/,?\s*&\w+/, '') if code_object.params + + code_object.block_params = param + + blankline + else + result = yield directive, param if block_given? + + case result + when nil then + code_object.metadata[directive] = param if code_object + + if RDoc::Markup::PreProcess.registered.include? directive then + handler = RDoc::Markup::PreProcess.registered[directive] + result = handler.call directive, param if handler + else result = "#{prefix}:#{directive}: #{param}\n" end + when false then + result = "#{prefix}:#{directive}: #{param}\n" + end - result - end + result end - - text end ## Index: lib/rdoc/markup/parser.rb =================================================================== --- lib/rdoc/markup/parser.rb (revision 32766) +++ lib/rdoc/markup/parser.rb (revision 32767) @@ -405,13 +405,19 @@ @line += 1 token # === text => :HEADER then :TEXT - when s.scan(/(=+)\s*/) then + when s.scan(/(=+)(\s*)/) then level = s[1].length - level = 6 if level > 6 - @tokens << [:HEADER, level, *token_pos(pos)] - pos = s.pos - s.scan(/.*/) - [:TEXT, s.matched.sub(/\r$/, ''), *token_pos(pos)] + header = [:HEADER, level, *token_pos(pos)] + + if s[2] =~ /^\r?\n/ then + s.pos -= s[2].length + header + else + pos = s.pos + s.scan(/.*/) + @tokens << header + [:TEXT, s.matched.sub(/\r$/, ''), *token_pos(pos)] + end # --- (at least 3) and nothing else on the line => :RULE when s.scan(/(-{3,}) *$/) then [:RULE, s[1].length - 2, *token_pos(pos)] Index: lib/rdoc/markup/formatter.rb =================================================================== --- lib/rdoc/markup/formatter.rb (revision 32766) +++ lib/rdoc/markup/formatter.rb (revision 32767) @@ -4,6 +4,10 @@ # Base class for RDoc markup formatters # # Formatters use a visitor pattern to convert content into output. +# +# If you'd like to write your own Formatter use +# RDoc::Markup::FormatterTestCase. If you're writing a text-output formatter +# use RDoc::Markup::TextFormatterTestCase which provides extra test cases. class RDoc::Markup::Formatter Index: lib/rdoc/markup/to_html.rb =================================================================== --- lib/rdoc/markup/to_html.rb (revision 32766) +++ lib/rdoc/markup/to_html.rb (revision 32767) @@ -70,7 +70,7 @@ @list = nil @from_path = '' - # external hyperlinks + # external links @markup.add_special(/((link:|https?:|mailto:|ftp:|www\.)\S+\w)/, :HYPERLINK) # and links of the form <text>[<url>] @@ -84,7 +84,7 @@ # These methods handle special markup added by RDoc::Markup#add_special. ## - # +special+ is a potential hyperlink. The following schemes are handled: + # +special+ is a potential link. The following schemes are handled: # # <tt>mailto:</tt>:: # Inserted as-is. @@ -97,12 +97,13 @@ def handle_special_HYPERLINK(special) url = special.text + gen_url url, url end ## - # This +special+ is a hyperlink where the label is different from the URL - # label[url] or {long label}[url] + # This +special+ is a link where the label is different from the URL + # <tt>label[url]</tt> or <tt>{long label}[url]</tt> def handle_special_TIDYLINK(special) text = special.text @@ -232,8 +233,8 @@ end ## - # Generate a hyperlink for +url+, labeled with +text+. Handles the special - # cases for img: and link: described under handle_special_HYPERLINK + # Generate a link for +url+, labeled with +text+. Handles the special cases + # for img: and link: described under handle_special_HYPERLINK def gen_url(url, text) if url =~ /([A-Za-z]+):(.*)/ then Index: lib/rdoc/markup/to_html_crossref.rb =================================================================== --- lib/rdoc/markup/to_html_crossref.rb (revision 32766) +++ lib/rdoc/markup/to_html_crossref.rb (revision 32767) @@ -1,94 +1,21 @@ require 'rdoc/markup/to_html' +require 'rdoc/cross_reference' ## -# Subclass of the RDoc::Markup::ToHtml class that supports looking up words -# from a context. Those that are found will be hyperlinked. +# Subclass of the RDoc::Markup::ToHtml class that supports looking up method +# names, classes, etc to create links. RDoc::CrossReference is used to +# generate those links based on the current context. class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml - ## - # Regular expression to match class references - # - # 1. There can be a '\\' in front of text to suppress the cross-reference - # 2. There can be a '::' in front of class names to reference from the - # top-level namespace. - # 3. The method can be followed by parenthesis (not recommended) + # :stopdoc: + ALL_CROSSREF_REGEXP = RDoc::CrossReference::ALL_CROSSREF_REGEXP + CLASS_REGEXP_STR = RDoc::CrossReference::CLASS_REGEXP_STR + CROSSREF_REGEXP = RDoc::CrossReference::CROSSREF_REGEXP + METHOD_REGEXP_STR = RDoc::CrossReference::METHOD_REGEXP_STR + # :startdoc: - CLASS_REGEXP_STR = '\\\\?((?:\:{2})?[A-Z]\w*(?:\:\:\w+)*)' - ## - # Regular expression to match method references. - # - # See CLASS_REGEXP_STR - - METHOD_REGEXP_STR = '([a-z]\w*[!?=]?)(?:\([\w.+*/=<>-]*\))?' - - ## - # Regular expressions matching text that should potentially have - # cross-reference links generated are passed to add_special. Note that - # these expressions are meant to pick up text for which cross-references - # have been suppressed, since the suppression characters are removed by the - # code that is triggered. - - CROSSREF_REGEXP = /( - # A::B::C.meth - #{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR} - - # Stand-alone method (preceded by a #) - | \\?\##{METHOD_REGEXP_STR} - - # Stand-alone method (preceded by ::) - | ::#{METHOD_REGEXP_STR} - - # A::B::C - # The stuff after CLASS_REGEXP_STR is a - # nasty hack. CLASS_REGEXP_STR unfortunately matches - # words like dog and cat (these are legal "class" - # names in Fortran 95). When a word is flagged as a - # potential cross-reference, limitations in the markup - # engine suppress other processing, such as typesetting. - # This is particularly noticeable for contractions. - # In order that words like "can't" not - # be flagged as potential cross-references, only - # flag potential class cross-references if the character - # after the cross-reference is a space, sentence - # punctuation, tag start character, or attribute - # marker. - | #{CLASS_REGEXP_STR}(?=[\s\)\.\?\!\,\;<\000]|\z) - - # Things that look like filenames - # The key thing is that there must be at least - # one special character (period, slash, or - # underscore). - | (?:\.\.\/)*[-\/\w]+[_\/\.][-\w\/\.]+ - - # Things that have markup suppressed - # Don't process things like '\<' in \<tt>, though. - # TODO: including < is a hack, not very satisfying. - | \\[^\s<] - )/x - - ## - # Version of CROSSREF_REGEXP used when <tt>--hyperlink-all</tt> is specified. - - ALL_CROSSREF_REGEXP = /( - # A::B::C.meth - #{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR} - - # Stand-alone method - | \\?#{METHOD_REGEXP_STR} - - # A::B::C - | #{CLASS_REGEXP_STR}(?=[\s\)\.\?\!\,\;<\000]|\z) - - # Things that look like filenames - | (?:\.\.\/)*[-\/\w]+[_\/\.][-\w\/\.]+ - - # Things that have markup suppressed - | \\[^\s<] - )/x - - ## # RDoc::CodeObject for generating references attr_accessor :context @@ -102,7 +29,7 @@ # Creates a new crossref resolver that generates links relative to +context+ # which lives at +from_path+ in the generated files. '#' characters on # references are removed unless +show_hash+ is true. Only method names - # preceded by '#' or '::' are hyperlinked, unless +hyperlink_all+ is true. + # preceded by '#' or '::' are linked, unless +hyperlink_all+ is true. def initialize(from_path, context, show_hash, hyperlink_all = false, markup = nil) @@ -111,22 +38,36 @@ crossref_re = hyperlink_all ? ALL_CROSSREF_REGEXP : CROSSREF_REGEXP + @cross_reference = RDoc::CrossReference.new context + @markup.add_special crossref_re, :CROSSREF + @markup.add_special(/rdoc-ref:\S+\w/, :HYPERLINK) - @from_path = from_path - @context = context - @show_hash = show_hash + @from_path = from_path @hyperlink_all = hyperlink_all + @show_hash = show_hash + end - @seen = {} + ## + # Creates a link to the reference +name+ if the name exists. If +text+ is + # given it is used as the link text, otherwise +name+ is used. + + def cross_reference name, text = nil + lookup = name + + name = name[1..-1] unless @show_hash if name[0, 1] == '#' + + text = name unless text + + link lookup, text end ## # We're invoked when any text matches the CROSSREF pattern. If we find the - # corresponding reference, generate a hyperlink. If the name we're looking - # for contains no punctuation, we look for it up the module/class chain. - # For example, ToHtml is found, even without the <tt>RDoc::Markup::</tt> - # prefix, because we look for it in module Markup first. + # corresponding reference, generate a link. If the name we're looking for + # contains no punctuation, we look for it up the module/class chain. For + # example, ToHtml is found, even without the <tt>RDoc::Markup::</tt> prefix, + # because we look for it in module Markup first. def handle_special_CROSSREF(special) name = special.text @@ -138,66 +79,41 @@ return name if name =~ /\A[a-z]*\z/ end - return @seen[name] if @seen.include? name + cross_reference name + end - lookup = name + ## (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/