Permalink
Browse files

* lib/rdoc: Update to RDoc 3.9. Fixed `ri []`, stopdoc creating an

	  object reference, nodoc for class aliases, verbatim === lines.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@32767 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
  • Loading branch information...
1 parent 4ac69a5 commit 89b601d176a64f1293a3d3b5195b6735cbf880af @drbrain drbrain committed Jul 31, 2011
View
@@ -1,3 +1,8 @@
+Sun Jul 31 09:18:28 2011 Eric Hodel <drbrain@segment7.net>
+
+ * 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@ruby-lang.org>
* io.c (rb_io_each_byte): remove unused variable e.
View
@@ -8,6 +8,13 @@
#
# $Revision$
+begin
+ gem 'rdoc'
+rescue NameError => e # --disable-gems
+ raise unless e.name == :gem
+rescue Gem::LoadError
+end
+
require 'rdoc/rdoc'
begin
View
7 bin/ri
@@ -1,5 +1,12 @@
#!/usr/bin/env ruby
+begin
+ gem 'rdoc'
+rescue NameError => e # --disable-gems
+ raise unless e.name == :gem
+rescue Gem::LoadError
+end
+
require 'rdoc/ri/driver'
RDoc::RI::Driver.run ARGV
View
@@ -104,7 +104,7 @@ def self.const_missing const_name # :nodoc:
##
# RDoc version you are using
- VERSION = '3.8'
+ VERSION = '3.9'
##
# Method visibilities
View
@@ -222,6 +222,9 @@ def full_name
end
end
+ ##
+ # TODO: filter included items by #display?
+
def marshal_dump # :nodoc:
attrs = attributes.sort.map do |attr|
[ attr.name, attr.rw,
View
@@ -114,6 +114,7 @@ def initialize
@done_documenting = false
@force_documentation = false
@received_nodoc = false
+ @ignored = false
end
##
@@ -140,6 +141,13 @@ def comment=(comment)
end
##
+ # Should this CodeObject be shown in documentation?
+
+ def display?
+ @document_self and not @ignored
+ end
+
+ ##
# Enables or disables documentation of this CodeObject's children unless it
# has been turned off by :enddoc:
@@ -195,6 +203,11 @@ def each_parent
self
end
+ ##
+ # File name where this CodeObject was found.
+ #
+ # See also RDoc::Context#in_files
+
def file_name
return unless @file
@@ -221,6 +234,34 @@ def full_name= full_name
end
##
+ # Use this to ignore a CodeObject and all its children until found again
+ # (#record_location is called). An ignored item will not be shown in
+ # documentation.
+ #
+ # See github issue #55
+ #
+ # The ignored status is temporary in order to allow implementation details
+ # to be hidden. At the end of processing a file RDoc allows all classes
+ # and modules to add new documentation to previously created classes.
+ #
+ # If a class was ignored (via stopdoc) then reopened later with additional
+ # documentation it should be shown. If a class was ignored and never
+ # reopened it should not be shown. The ignore flag allows this to occur.
+
+ def ignore
+ @ignored = true
+
+ stop_doc
+ end
+
+ ##
+ # Has this class been ignored?
+
+ def ignored?
+ @ignored
+ end
+
+ ##
# File name of our parent
def parent_file_name
@@ -238,6 +279,7 @@ def parent_name
# Records the RDoc::TopLevel (file) where this code object was defined
def record_location top_level
+ @ignored = false
@file = top_level
end
@@ -250,6 +292,7 @@ def start_doc
@document_self = true
@document_children = true
+ @ignored = false
end
##
View
@@ -423,6 +423,7 @@ def add_class class_type, given_name, superclass = '::Object'
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 @@ def add_to(array, thing)
##
# 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)
View
@@ -0,0 +1,173 @@
+##
+# RDoc::CrossReference is a reusable way to create cross references for names.
+
+class RDoc::CrossReference
+
+ ##
+ # 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)
+
+ 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
+
+ attr_accessor :seen
+
+ ##
+ # Allows cross-references to be created based on the given +context+
+ # (RDoc::Context).
+
+ def initialize context
+ @context = context
+
+ @seen = {}
+ end
+
+ ##
+ # Returns a reference to +name+.
+ #
+ # If the reference is found and +name+ is not documented +text+ will be
+ # returned. If +name+ is escaped +name+ is returned. If +name+ is not
+ # found +text+ is returned.
+
+ def resolve name, text
+ return @seen[name] if @seen.include? name
+
+ # Find class, module, or method in class or module.
+ #
+ # Do not, however, use an if/elsif/else chain to do so. Instead, test
+ # each possible pattern until one matches. The reason for this is that a
+ # string like "YAML.txt" could be the txt() class method of class YAML (in
+ # which case it would match the first pattern, which splits the string
+ # into container and method components and looks up both) or a filename
+ # (in which case it would match the last pattern, which just checks
+ # whether the string as a whole is a known symbol).
+
+ if /#{CLASS_REGEXP_STR}([.#]|::)#{METHOD_REGEXP_STR}/o =~ name then
+ type = $2
+ type = '' if type == '.' # will find either #method or ::method
+ method = "#{type}#{$3}"
+ container = @context.find_symbol_module($1)
+ elsif /^([.#]|::)#{METHOD_REGEXP_STR}/o =~ name then
+ type = $1
+ type = '' if type == '.'
+ method = "#{type}#{$2}"
+ container = @context
+ else
+ container = nil
+ end
+
+ if container then
+ ref = container.find_local_symbol method
+
+ unless ref || RDoc::TopLevel === container then
+ ref = container.find_ancestor_local_symbol method
+ end
+ end
+
+ ref = case name
+ when /^\\(#{CLASS_REGEXP_STR})$/o then
+ ref = @context.find_symbol $1
+ else
+ ref = @context.find_symbol name
+ end unless ref
+
+ ref = nil if RDoc::Alias === ref # external alias: can't link to it
+
+ out = if name == '\\' then
+ name
+ elsif name =~ /^\\/ then
+ # we remove the \ only in front of what we know:
+ # other backslashes are treated later, only outside of <tt>
+ ref ? $' : name
+ elsif ref then
+ if ref.display? then
+ ref
+ else
+ text
+ end
+ else
+ text
+ end
+
+ @seen[name] = out
+
+ out
+ end
+
+end
+
@@ -192,7 +192,7 @@ def get_sorted_module_list(classes)
top_level = klass.full_name.gsub( /::.*/, '' )
[nscounts[top_level] * -1, klass.full_name]
end.select do |klass|
- klass.document_self
+ klass.display?
end
end
@@ -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">
Oops, something went wrong.

0 comments on commit 89b601d

Please sign in to comment.