Permalink
Browse files

* lib/rdoc*: Updated to RDoc 4.0 (pre-release)

* bin/rdoc:  ditto
* test/rdoc:  ditto
* NEWS:  Updated with RDoc 4.0 information


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@37889 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
  • Loading branch information...
1 parent c72f0da commit 1c279a7d2753949c725754e1302f791b76358114 @drbrain drbrain committed Nov 27, 2012
Showing with 28,501 additions and 3,169 deletions.
  1. +7 −0 ChangeLog
  2. +11 −0 NEWS
  3. +4 −2 bin/rdoc
  4. +1 −1 ext/nkf/nkf-utf8/utf8tbl.c
  5. +103 −68 lib/rdoc.rb
  6. +0 −2 lib/rdoc/alias.rb
  7. +0 −2 lib/rdoc/anon_class.rb
  8. +80 −25 lib/rdoc/any_method.rb
  9. +48 −11 lib/rdoc/attr.rb
  10. +227 −40 lib/rdoc/class_module.rb
  11. +55 −15 lib/rdoc/code_object.rb
  12. +3 −21 lib/rdoc/code_objects.rb
  13. +232 −0 lib/rdoc/comment.rb
  14. +100 −8 lib/rdoc/constant.rb
  15. +160 −163 lib/rdoc/context.rb
  16. +238 −0 lib/rdoc/context/section.rb
  17. +73 −63 lib/rdoc/cross_reference.rb
  18. +34 −31 lib/rdoc/encoding.rb
  19. +18 −0 lib/rdoc/erb_partial.rb
  20. +117 −0 lib/rdoc/extend.rb
  21. +21 −11 lib/rdoc/generator.rb
  22. +399 −67 lib/rdoc/generator/darkfish.rb
  23. +248 −0 lib/rdoc/generator/json_index.rb
  24. +24 −63 lib/rdoc/generator/markup.rb
  25. +7 −63 lib/rdoc/generator/ri.rb
  26. +5 −0 lib/rdoc/generator/template/darkfish/_footer.rhtml
  27. +16 −0 lib/rdoc/generator/template/darkfish/_head.rhtml
  28. +18 −0 lib/rdoc/generator/template/darkfish/_sidebar_VCS_info.rhtml
  29. +9 −0 lib/rdoc/generator/template/darkfish/_sidebar_classes.rhtml
  30. +16 −0 lib/rdoc/generator/template/darkfish/_sidebar_extends.rhtml
  31. +8 −0 lib/rdoc/generator/template/darkfish/_sidebar_in_files.rhtml
  32. +16 −0 lib/rdoc/generator/template/darkfish/_sidebar_includes.rhtml
  33. +14 −0 lib/rdoc/generator/template/darkfish/_sidebar_installed.rhtml
  34. +12 −0 lib/rdoc/generator/template/darkfish/_sidebar_methods.rhtml
  35. +7 −0 lib/rdoc/generator/template/darkfish/_sidebar_navigation.rhtml
  36. +12 −0 lib/rdoc/generator/template/darkfish/_sidebar_pages.rhtml
  37. +10 −0 lib/rdoc/generator/template/darkfish/_sidebar_parent.rhtml
  38. +10 −0 lib/rdoc/generator/template/darkfish/_sidebar_search.rhtml
  39. +10 −0 lib/rdoc/generator/template/darkfish/_sidebar_sections.rhtml
  40. +13 −0 lib/rdoc/generator/template/darkfish/_sidebar_table_of_contents.rhtml
  41. +179 −0 lib/rdoc/generator/template/darkfish/class.rhtml
  42. +0 −321 lib/rdoc/generator/template/darkfish/classpage.rhtml
  43. +0 −124 lib/rdoc/generator/template/darkfish/filepage.rhtml
  44. BIN lib/rdoc/generator/template/darkfish/images/add.png
  45. BIN lib/rdoc/generator/template/darkfish/images/arrow_up.png
  46. BIN lib/rdoc/generator/template/darkfish/images/delete.png
  47. BIN lib/rdoc/generator/template/darkfish/images/tag_blue.png
  48. BIN lib/rdoc/generator/template/darkfish/images/transparent.png
  49. +16 −61 lib/rdoc/generator/template/darkfish/index.rhtml
  50. +99 −62 lib/rdoc/generator/template/darkfish/js/darkfish.js
  51. +15 −29 lib/rdoc/generator/template/darkfish/js/jquery.js
  52. +0 −114 lib/rdoc/generator/template/darkfish/js/quicksearch.js
  53. +94 −0 lib/rdoc/generator/template/darkfish/js/search.js
  54. +0 −10 lib/rdoc/generator/template/darkfish/js/thickbox-compressed.js
  55. +18 −0 lib/rdoc/generator/template/darkfish/page.rhtml
  56. +149 −338 lib/rdoc/generator/template/darkfish/rdoc.css
  57. +18 −0 lib/rdoc/generator/template/darkfish/servlet_not_found.rhtml
  58. +37 −0 lib/rdoc/generator/template/darkfish/servlet_root.rhtml
  59. +55 −0 lib/rdoc/generator/template/darkfish/table_of_contents.rhtml
  60. +142 −0 lib/rdoc/generator/template/json_index/js/navigation.js
  61. +228 −0 lib/rdoc/generator/template/json_index/js/searcher.js
  62. +0 −2 lib/rdoc/ghost_method.rb
  63. +31 −12 lib/rdoc/include.rb
  64. +16,372 −0 lib/rdoc/markdown.rb
  65. +2,128 −0 lib/rdoc/markdown/entities.rb
  66. +417 −0 lib/rdoc/markdown/literals_1_9.rb
  67. +268 −48 lib/rdoc/markup.rb
  68. +22 −0 lib/rdoc/markup/attr_changer.rb
  69. +29 −0 lib/rdoc/markup/attr_span.rb
  70. +23 −14 lib/rdoc/markup/attribute_manager.rb
  71. +70 −0 lib/rdoc/markup/attributes.rb
  72. +14 −0 lib/rdoc/markup/block_quote.rb
  73. +41 −4 lib/rdoc/markup/document.rb
  74. +31 −16 lib/rdoc/markup/formatter.rb
  75. +94 −26 lib/rdoc/markup/formatter_test_case.rb
  76. +31 −0 lib/rdoc/markup/hard_break.rb
  77. +44 −0 lib/rdoc/markup/heading.rb
  78. +42 −0 lib/rdoc/markup/include.rb
  79. +14 −0 lib/rdoc/markup/indented_paragraph.rb
  80. +1 −144 lib/rdoc/markup/inline.rb
  81. +24 −4 lib/rdoc/markup/list.rb
  82. +17 −4 lib/rdoc/markup/list_item.rb
  83. +14 −0 lib/rdoc/markup/paragraph.rb
  84. +119 −70 lib/rdoc/markup/parser.rb
  85. +77 −11 lib/rdoc/markup/pre_process.rb
  86. +5 −5 lib/rdoc/markup/raw.rb
  87. +40 −0 lib/rdoc/markup/special.rb
  88. +0 −2 lib/rdoc/markup/text_formatter_test_case.rb
  89. +12 −3 lib/rdoc/markup/to_ansi.rb
  90. +0 −2 lib/rdoc/markup/to_bs.rb
  91. +138 −40 lib/rdoc/markup/to_html.rb
  92. +50 −13 lib/rdoc/markup/to_html_crossref.rb
  93. +284 −0 lib/rdoc/markup/to_html_snippet.rb
  94. +68 −0 lib/rdoc/markup/to_joined_paragraph.rb
  95. +74 −0 lib/rdoc/markup/to_label.rb
  96. +134 −0 lib/rdoc/markup/to_markdown.rb
  97. +42 −10 lib/rdoc/markup/to_rdoc.rb
  98. +61 −0 lib/rdoc/markup/to_table_of_contents.rb
  99. +0 −3 lib/rdoc/markup/to_test.rb
  100. +11 −5 lib/rdoc/markup/to_tt_only.rb
  101. +38 −0 lib/rdoc/markup/verbatim.rb
  102. +0 −2 lib/rdoc/meta_method.rb
  103. +62 −19 lib/rdoc/method_attr.rb
  104. +26 −9 lib/rdoc/normal_class.rb
  105. +10 −7 lib/rdoc/normal_module.rb
  106. +325 −16 lib/rdoc/options.rb
  107. +88 −58 lib/rdoc/parser.rb
  108. +293 −201 lib/rdoc/parser/c.rb
  109. +23 −0 lib/rdoc/parser/markdown.rb
  110. +22 −0 lib/rdoc/parser/rd.rb
  111. +213 −99 lib/rdoc/parser/ruby.rb
  112. +8 −3 lib/rdoc/parser/ruby_tools.rb
  113. +21 −9 lib/rdoc/parser/simple.rb
  114. +11 −0 lib/rdoc/parser/text.rb
  115. +99 −0 lib/rdoc/rd.rb
  116. +1,054 −0 lib/rdoc/rd/block_parser.rb
  117. +71 −0 lib/rdoc/rd/inline.rb
  118. +1,207 −0 lib/rdoc/rd/inline_parser.rb
  119. +102 −70 lib/rdoc/rdoc.rb
  120. +0 −2 lib/rdoc/require.rb
  121. +4 −2 lib/rdoc/ri.rb
  122. +322 −82 lib/rdoc/ri/driver.rb
  123. +90 −31 lib/rdoc/ri/paths.rb
  124. +2 −354 lib/rdoc/ri/store.rb
  125. +82 −43 lib/rdoc/ruby_lex.rb
  126. +46 −4 lib/rdoc/ruby_token.rb
  127. +4 −5 lib/rdoc/rubygems_hook.rb
Sorry, we could not display the entire diff because it was too big.
View
7 ChangeLog
@@ -1,3 +1,10 @@
+Tue Nov 27 13:27:46 2012 Eric Hodel <drbrain@segment7.net>
+
+ * lib/rdoc*: Updated to RDoc 4.0 (pre-release)
@anatol
anatol Dec 11, 2013

RDoc 4.10 is out and brings many bugfixes.

Is there any chance to see it merged into ruby sources?

@zzak
zzak Dec 11, 2013

@anatol RDoc 4.1.0* is only in preview release, it will be released soon and merged into trunk before the 2.1.0 release this Christmas.

That said, Eric is the current maintainer of RDoc and I think he's more than capable of handling the merge, please stay tuned ;)

@drbrain
drbrain Dec 12, 2013

An RDoc 4.1 prerelease is already merged to trunk, please check ChangeLog and NEWS.

+ * bin/rdoc: ditto
+ * test/rdoc*: ditto
+ * NEWS: Updated with RDoc 4.0 information
+
Tue Nov 27 12:17:11 2012 Koichi Sasada <ko1@atdot.net>
* thread.c (rb_thread_terminate_all): retry broadcast only when
View
11 NEWS
@@ -272,6 +272,17 @@ with all sufficient information, see the ChangeLog file.
http://rake.rubyforge.org/doc/release_notes/rake-0_9_4_rdoc.html for a list
of changes in rake 0.9.3 and 0.9.4.
+* rdoc
+ * rdoc has been updated to version 4.0
+
+ This version is largely backwards-compatible with previous rdoc versions.
+ The most notable change is an update to the ri data format (ri data must
+ be regenerated for gems shared across rdoc versions). Further API changes
+ are internal and won't affect most users.
+
+ See https://github.com/rdoc/rdoc/blob/master/History.rdoc for a list of
+ changes in rdoc 4.0.
+
* resolv
* new methods:
* Resolv::DNS#timeouts=
View
6 bin/rdoc
@@ -5,8 +5,6 @@
#
# Copyright (c) 2003 Dave Thomas
# Released under the same terms as Ruby
-#
-# $Revision$
begin
gem 'rdoc'
@@ -20,6 +18,10 @@ require 'rdoc/rdoc'
begin
r = RDoc::RDoc.new
r.document ARGV
+rescue Errno::ENOSPC
+ $stderr.puts 'Ran out of space creating documentation'
+ $stderr.puts
+ $stderr.puts 'Please free up some space and try again'
rescue SystemExit
raise
rescue Exception => e
View
2 ext/nkf/nkf-utf8/utf8tbl.c
@@ -1,7 +1,7 @@
/*
* utf8tbl.c - Convertion Table for nkf
*
- * $Id: utf8tbl.c,v 1.23 2008/02/07 19:25:29 naruse Exp $
+ * $Id$
*/
#include "config.h"
View
171 lib/rdoc.rb
@@ -1,86 +1,55 @@
$DEBUG_RDOC = nil
-# :main: README.txt
+# :main: README.rdoc
##
-# RDoc is a Ruby documentation system which contains RDoc::RDoc for generating
-# documentation, RDoc::RI for interactive documentation and RDoc::Markup for
-# text markup.
+# RDoc produces documentation for Ruby source files by parsing the source and
+# extracting the definition for classes, modules, methods, includes and
+# requires. It associates these with optional documentation contained in an
+# immediately preceding comment block then renders the result using an output
+# formatter.
#
-# RDoc::RDoc produces documentation for Ruby source files. It works similarly
-# to JavaDoc, parsing the source and extracting the definition for classes,
-# modules, methods, includes and requires. It associates these with optional
-# documentation contained in an immediately preceding comment block then
-# renders the result using an output formatter.
-#
-# RDoc::Markup that converts plain text into various output formats. The
-# markup library is used to interpret the comment blocks that RDoc uses to
-# document methods, classes, and so on.
-#
-# RDoc::RI implements the +ri+ command-line tool which displays on-line
-# documentation for ruby classes, methods, etc. +ri+ features several output
-# formats and an interactive mode (<tt>ri -i</tt>). See <tt>ri --help</tt>
-# for further details.
+# For a simple introduction to writing or generating documentation using RDoc
+# see the README.
#
# == Roadmap
#
-# * If you want to use RDoc to create documentation for your Ruby source files,
-# see RDoc::Markup and refer to <tt>rdoc --help</tt> for command line
-# usage.
-# * If you want to write documentation for Ruby files see RDoc::Parser::Ruby
-# * If you want to write documentation for extensions written in C see
-# RDoc::Parser::C
-# * If you want to generate documentation using <tt>rake</tt> see RDoc::Task.
-# * If you want to drive RDoc programmatically, see RDoc::RDoc.
-# * If you want to use the library to format text blocks into HTML, look at
-# RDoc::Markup.
-# * If you want to make an RDoc plugin such as a generator or directive
-# handler see RDoc::RDoc.
-# * If you want to write your own output generator see RDoc::Generator.
-#
-# == Summary
+# If you think you found a bug in RDoc see DEVELOPERS@Bugs
#
-# Once installed, you can create documentation using the +rdoc+ command
+# If you want to use RDoc to create documentation for your Ruby source files,
+# see RDoc::Markup and refer to <tt>rdoc --help</tt> for command line usage.
#
-# % rdoc [options] [names...]
+# If you want to set the default markup format see
+# RDoc::Markup@Supported+Formats
#
-# For an up-to-date option summary, type
+# If you want to store rdoc configuration in your gem (such as the default
+# markup format) see RDoc::Options@Saved+Options
#
-# % rdoc --help
+# If you want to write documentation for Ruby files see RDoc::Parser::Ruby
#
-# A typical use might be to generate documentation for a package of Ruby
-# source (such as RDoc itself).
+# If you want to write documentation for extensions written in C see
+# RDoc::Parser::C
#
-# % rdoc
+# If you want to generate documentation using <tt>rake</tt> see RDoc::Task.
#
-# This command generates documentation for all the Ruby and C source
-# files in and below the current directory. These will be stored in a
-# documentation tree starting in the subdirectory +doc+.
+# If you want to drive RDoc programmatically, see RDoc::RDoc.
#
-# You can make this slightly more useful for your readers by having the
-# index page contain the documentation for the primary file. In our
-# case, we could type
+# If you want to use the library to format text blocks into HTML or other
+# formats, look at RDoc::Markup.
#
-# % rdoc --main README.txt
+# If you want to make an RDoc plugin such as a generator or directive handler
+# see RDoc::RDoc.
#
-# You'll find information on the various formatting tricks you can use
-# in comment blocks in the documentation this generates.
+# If you want to write your own output generator see RDoc::Generator.
#
-# RDoc uses file extensions to determine how to process each file. File names
-# ending +.rb+ and +.rbw+ are assumed to be Ruby source. Files
-# ending +.c+ are parsed as C files. All other files are assumed to
-# contain just Markup-style markup (with or without leading '#' comment
-# markers). If directory names are passed to RDoc, they are scanned
-# recursively for C and Ruby source files only.
+# If you want an overview of how RDoc works see DEVELOPERS
#
-# == Other stuff
+# == Credits
#
# RDoc is currently being maintained by Eric Hodel <drbrain@segment7.net>.
#
# Dave Thomas <dave@pragmaticprogrammer.com> is the original author of RDoc.
#
-# == Credits
-#
# * The Ruby parser in rdoc/parse.rb is based heavily on the outstanding
# work of Keiju ISHITSUKA of Nippon Rational Inc, who produced the Ruby
# parser for irb and the rtags package.
@@ -92,19 +61,10 @@ module RDoc
class Error < RuntimeError; end
- def self.const_missing const_name # :nodoc:
- if const_name.to_s == 'RDocError' then
- warn "RDoc::RDocError is deprecated"
- return Error
- end
-
- super
- end
-
##
# RDoc version you are using
- VERSION = '3.9.4'
+ VERSION = '4.0'
##
# Method visibilities
@@ -143,5 +103,80 @@ def self.const_missing const_name # :nodoc:
METHOD_MODIFIERS = GENERAL_MODIFIERS +
%w[arg args yield yields notnew not-new not_new doc]
+ ##
+ # Loads the best available YAML library.
+
+ def self.load_yaml
+ begin
+ gem 'psych'
+ rescue Gem::LoadError
+ end
+
+ begin
+ require 'psych'
+ rescue ::LoadError
+ ensure
+ require 'yaml'
+ end
+ end
+
+ autoload :RDoc, 'rdoc/rdoc'
+
+ autoload :TestCase, 'rdoc/test_case'
+
+ autoload :CrossReference, 'rdoc/cross_reference'
+ autoload :ERBIO, 'rdoc/erbio'
+ autoload :ERBPartial, 'rdoc/erb_partial'
+ autoload :Encoding, 'rdoc/encoding'
+ autoload :Generator, 'rdoc/generator'
+ autoload :Options, 'rdoc/options'
+ autoload :Parser, 'rdoc/parser'
+ autoload :Servlet, 'rdoc/servlet'
+ autoload :RI, 'rdoc/ri'
+ autoload :Stats, 'rdoc/stats'
+ autoload :Store, 'rdoc/store'
+ autoload :Task, 'rdoc/task'
+ autoload :Text, 'rdoc/text'
+
+ autoload :Markdown, 'rdoc/markdown'
+ autoload :Markup, 'rdoc/markup'
+ autoload :RD, 'rdoc/rd'
+ autoload :TomDoc, 'rdoc/tom_doc'
+
+ autoload :KNOWN_CLASSES, 'rdoc/known_classes'
+
+ autoload :RubyLex, 'rdoc/ruby_lex'
+ autoload :RubyToken, 'rdoc/ruby_token'
+ autoload :TokenStream, 'rdoc/token_stream'
+
+ autoload :Comment, 'rdoc/comment'
+
+ # code objects
+ #
+ # We represent the various high-level code constructs that appear in Ruby
+ # programs: classes, modules, methods, and so on.
+ autoload :CodeObject, 'rdoc/code_object'
+
+ autoload :Context, 'rdoc/context'
+ autoload :TopLevel, 'rdoc/top_level'
+
+ autoload :AnonClass, 'rdoc/anon_class'
+ autoload :ClassModule, 'rdoc/class_module'
+ autoload :NormalClass, 'rdoc/normal_class'
+ autoload :NormalModule, 'rdoc/normal_module'
+ autoload :SingleClass, 'rdoc/single_class'
+
+ autoload :Alias, 'rdoc/alias'
+ autoload :AnyMethod, 'rdoc/any_method'
+ autoload :MethodAttr, 'rdoc/method_attr'
+ autoload :GhostMethod, 'rdoc/ghost_method'
+ autoload :MetaMethod, 'rdoc/meta_method'
+ autoload :Attr, 'rdoc/attr'
+
+ autoload :Constant, 'rdoc/constant'
+ autoload :Include, 'rdoc/include'
+ autoload :Extend, 'rdoc/extend'
+ autoload :Require, 'rdoc/require'
+
end
View
2 lib/rdoc/alias.rb
@@ -1,5 +1,3 @@
-require 'rdoc/code_object'
-
##
# Represent an alias, which is an old_name/new_name pair associated with a
# particular context
View
2 lib/rdoc/anon_class.rb
@@ -1,5 +1,3 @@
-require 'rdoc/class_module'
-
##
# An anonymous class like:
#
View
105 lib/rdoc/any_method.rb
@@ -1,12 +1,16 @@
-require 'rdoc/method_attr'
-require 'rdoc/token_stream'
-
##
# AnyMethod is the base class for objects representing methods
class RDoc::AnyMethod < RDoc::MethodAttr
- MARSHAL_VERSION = 1 # :nodoc:
+ ##
+ # 2::
+ # RDoc 4
+ # Added calls_super
+ # Added parent name and class
+ # Added section title
+
+ MARSHAL_VERSION = 2 # :nodoc:
##
# Don't rename \#initialize to \::new
@@ -28,6 +32,11 @@ class RDoc::AnyMethod < RDoc::MethodAttr
attr_accessor :params
+ ##
+ # If true this method uses +super+ to call a superclass version
+
+ attr_accessor :calls_super
+
include RDoc::TokenStream
##
@@ -39,6 +48,8 @@ def initialize text, name
@c_function = nil
@dont_rename_initialize = false
@token_stream = nil
+ @calls_super = false
+ @superclass_method = nil
end
##
@@ -97,6 +108,10 @@ def marshal_dump
aliases,
@params,
@file.absolute_name,
+ @calls_super,
+ @parent.name,
+ @parent.class,
+ @section.title,
]
end
@@ -107,34 +122,44 @@ def marshal_dump
# * #full_name
# * #parent_name
- def marshal_load(array)
+ def marshal_load array
@dont_rename_initialize = nil
@is_alias_for = nil
@token_stream = nil
@aliases = []
-
- version = array[0]
- @name = array[1]
- @full_name = array[2]
- @singleton = array[3]
- @visibility = array[4]
- @comment = array[5]
- @call_seq = array[6]
- @block_params = array[7]
+ @parent = nil
+ @parent_name = nil
+ @parent_class = nil
+ @section = nil
+ @file = nil
+
+ version = array[0]
+ @name = array[1]
+ @full_name = array[2]
+ @singleton = array[3]
+ @visibility = array[4]
+ @comment = array[5]
+ @call_seq = array[6]
+ @block_params = array[7]
+ # 8 handled below
+ @params = array[9]
+ # 10 handled below
+ @calls_super = array[11]
+ @parent_name = array[12]
+ @parent_title = array[13]
+ @section_title = array[14]
array[8].each do |new_name, comment|
add_alias RDoc::Alias.new(nil, @name, new_name, comment, @singleton)
end
- @params = array[9]
-
- @parent_name = if @full_name =~ /#/ then
- $`
- else
- name = @full_name.split('::')
- name.pop
- name.join '::'
- end
+ @parent_name ||= if @full_name =~ /#/ then
+ $`
+ else
+ name = @full_name.split('::')
+ name.pop
+ name.join '::'
+ end
@file = RDoc::TopLevel.new array[10] if version > 0
end
@@ -169,7 +194,9 @@ def param_list
return []
end
- params.gsub(/\s+/, '').split ','
+ params = params.gsub(/\s+/, '').split ','
+
+ params.map { |param| param.sub(/=.*/, '') }
end
##
@@ -181,10 +208,12 @@ def param_seq
params = @call_seq.split("\n").last
params = params.sub(/[^( ]+/, '')
params = params.sub(/(\|[^|]+\|)\s*\.\.\.\s*(end|\})/, '\1 \2')
- else
+ elsif @params then
params = @params.gsub(/\s*\#.*/, '')
params = params.tr("\n", " ").squeeze(" ")
params = "(#{params})" unless params[0] == ?(
+ else
+ params = ''
end
if @block_params then
@@ -203,5 +232,31 @@ def param_seq
params
end
+ ##
+ # Sets the store for this method and its referenced code objects.
+
+ def store= store
+ super
+
+ @file = @store.add_file @file.full_name if @file
+ end
+
+ ##
+ # For methods that +super+, find the superclass method that would be called.
+
+ def superclass_method
+ return unless @calls_super
+ return @superclass_method if @superclass_method
+
+ parent.each_ancestor do |ancestor|
+ if method = ancestor.method_list.find { |m| m.name == @name } then
+ @superclass_method = method
+ break
+ end
+ end
+
+ @superclass_method
+ end
+
end
View
59 lib/rdoc/attr.rb
@@ -1,12 +1,16 @@
-require 'rdoc/method_attr'
-
##
# An attribute created by \#attr, \#attr_reader, \#attr_writer or
# \#attr_accessor
class RDoc::Attr < RDoc::MethodAttr
- MARSHAL_VERSION = 2 # :nodoc:
+ ##
+ # 3::
+ # RDoc 4
+ # Added parent name and class
+ # Added section title
+
+ MARSHAL_VERSION = 3 # :nodoc:
##
# Is the attribute readable ('R'), writable ('W') or both ('RW')?
@@ -58,6 +62,16 @@ def aref_prefix
end
##
+ # Attributes never call super. See RDoc::AnyMethod#calls_super
+ #
+ # An RDoc::Attr can show up in the method list in some situations (see
+ # Gem::ConfigFile)
+
+ def calls_super # :nodoc:
+ false
+ end
+
+ ##
# Returns attr_reader, attr_writer or attr_accessor as appropriate.
def definition
@@ -93,6 +107,9 @@ def marshal_dump
parse(@comment),
singleton,
@file.absolute_name,
+ @parent.full_name,
+ @parent.class,
+ @section.title
]
end
@@ -104,17 +121,28 @@ def marshal_dump
# * #parent_name
def marshal_load array
- version = array[0]
- @name = array[1]
- @full_name = array[2]
- @rw = array[3]
- @visibility = array[4]
- @comment = array[5]
- @singleton = array[6] || false # MARSHAL_VERSION == 0
+ @aliases = []
+ @parent = nil
+ @parent_name = nil
+ @parent_class = nil
+ @section = nil
+ @file = nil
+
+ version = array[0]
+ @name = array[1]
+ @full_name = array[2]
+ @rw = array[3]
+ @visibility = array[4]
+ @comment = array[5]
+ @singleton = array[6] || false # MARSHAL_VERSION == 0
+ # 7 handled below
+ @parent_name = array[8]
+ @parent_class = array[9]
+ @section_title = array[10]
@file = RDoc::TopLevel.new array[7] if version > 1
- @parent_name = @full_name
+ @parent_name ||= @full_name.split('#', 2).first
end
def pretty_print q # :nodoc:
@@ -132,5 +160,14 @@ def to_s # :nodoc:
"#{definition} #{name} in: #{parent}"
end
+ ##
+ # Attributes do not have token streams.
+ #
+ # An RDoc::Attr can show up in the method list in some situations (see
+ # Gem::ConfigFile)
+
+ def token_stream # :nodoc:
+ end
+
end
View
267 lib/rdoc/class_module.rb
@@ -1,5 +1,3 @@
-require 'rdoc/context'
-
##
# ClassModule is the base class for objects representing either a class or a
# module.
@@ -13,8 +11,17 @@ class RDoc::ClassModule < RDoc::Context
# * Added file to constants
# * Added file to includes
# * Added file to methods
-
- MARSHAL_VERSION = 1 # :nodoc:
+ # 2::
+ # RDoc 3.13
+ # * Added extends
+ # 3::
+ # RDoc 4.0
+ # * Added sections
+ # * Added in_files
+ # * Added parent name
+ # * Complete Constant dump
+
+ MARSHAL_VERSION = 3 # :nodoc:
##
# Constants that are aliases for this class or module
@@ -56,6 +63,7 @@ def self.from_module class_type, mod
klass.external_aliases.concat mod.external_aliases
klass.constants.concat mod.constants
klass.includes.concat mod.includes
+ klass.extends.concat mod.extends
klass.methods_hash.update mod.methods_hash
klass.constants_hash.update mod.constants_hash
@@ -84,6 +92,7 @@ def self.from_module class_type, mod
klass.external_aliases +
klass.constants +
klass.includes +
+ klass.extends +
klass.classes +
klass.modules).each do |obj|
obj.parent = klass
@@ -115,16 +124,32 @@ def initialize(name, superclass = nil)
# across multiple runs.
def add_comment comment, location
- return if comment.empty? or not document_self
+ return unless document_self
original = comment
- comment = normalize_comment comment
+ comment = case comment
+ when RDoc::Comment then
+ comment.normalize
+ else
+ normalize_comment comment
+ end
@comment_location << [comment, location]
self.comment = original
end
+ def add_things my_things, other_things # :nodoc:
+ other_things.each do |group, things|
+ my_things[group].each { |thing| yield false, thing } if
+ my_things.include? group
+
+ things.each do |thing|
+ yield true, thing
+ end
+ end
+ end
+
##
# Ancestors list for this ClassModule: the list of included modules
# (classes will add their superclass if any).
@@ -142,6 +167,11 @@ def ancestors
end
##
+ # Ancestors of this class or module only
+
+ alias direct_ancestors ancestors
+
+ ##
# Clears the comment. Used by the ruby parser.
def clear_comment
@@ -155,9 +185,13 @@ def clear_comment
# more like <tt>+=</tt>.
def comment= comment
- return if comment.empty?
+ comment = case comment
+ when RDoc::Comment then
+ comment.normalize
+ else
+ normalize_comment comment
+ end
- comment = normalize_comment comment
comment = "#{@comment}\n---\n#{comment}" unless @comment.empty?
super comment
@@ -166,7 +200,7 @@ def comment= comment
##
# Prepares this ClassModule for use by a generator.
#
- # See RDoc::TopLevel::complete
+ # See RDoc::Store#complete
def complete min_visibility
update_aliases
@@ -176,12 +210,22 @@ def complete min_visibility
end
##
+ # Does this ClassModule or any of its methods have document_self set?
+
+ def document_self_or_methods
+ document_self || method_list.any?{ |m| m.document_self }
+ end
+
+ ##
# Iterates the ancestors of this class or module for which an
# RDoc::ClassModule exists.
def each_ancestor # :yields: module
+ return enum_for __method__ unless block_given?
+
ancestors.each do |mod|
next if String === mod
+ next if self == mod
yield mod
end
end
@@ -215,8 +259,8 @@ def find_class_named name
# Return the fully qualified name of this class or module
def full_name
- @full_name ||= if RDoc::ClassModule === @parent then
- "#{@parent.full_name}::#{@name}"
+ @full_name ||= if RDoc::ClassModule === parent then
+ "#{parent.full_name}::#{@name}"
else
@name
end
@@ -250,13 +294,20 @@ def marshal_dump # :nodoc:
@superclass,
parse(@comment_location),
attrs,
- constants.map do |const|
- [const.name, parse(const.comment), const.file_name]
- end,
+ constants,
includes.map do |incl|
[incl.name, parse(incl.comment), incl.file_name]
end,
method_types,
+ extends.map do |ext|
+ [ext.name, parse(ext.comment), ext.file_name]
+ end,
+ @sections.values,
+ @in_files.map do |tl|
+ tl.absolute_name
+ end,
+ parent.full_name,
+ parent.class,
]
end
@@ -268,6 +319,8 @@ def marshal_load array # :nodoc:
@parent = nil
@temporary_section = nil
@visibility = nil
+ @classes = {}
+ @modules = {}
@name = array[1]
@full_name = array[2]
@@ -291,9 +344,14 @@ def marshal_load array # :nodoc:
attr.record_location RDoc::TopLevel.new file
end
- array[6].each do |name, comment, file|
- const = add_constant RDoc::Constant.new(name, nil, comment)
- const.record_location RDoc::TopLevel.new file
+ array[6].each do |constant, comment, file|
+ case constant
+ when RDoc::Constant then
+ add_constant constant
+ else
+ constant = add_constant RDoc::Constant.new(constant, nil, comment)
+ constant.record_location RDoc::TopLevel.new file
+ end
end
array[7].each do |name, comment, file|
@@ -313,6 +371,27 @@ def marshal_load array # :nodoc:
end
end
end
+
+ array[9].each do |name, comment, file|
+ ext = add_extend RDoc::Extend.new(name, comment)
+ ext.record_location RDoc::TopLevel.new file
+ end if array[9] # Support Marshal version 1
+
+ sections = (array[10] || []).map do |section|
+ [section.title, section]
+ end
+
+ @sections = Hash[*sections.flatten]
+ @current_section = add_section nil
+
+ @in_files = []
+
+ (array[11] || []).each do |filename|
+ record_location RDoc::TopLevel.new filename
+ end
+
+ @parent_name = array[12]
+ @parent_class = array[13]
end
##
@@ -321,6 +400,9 @@ def marshal_load array # :nodoc:
# The data in +class_module+ is preferred over the receiver.
def merge class_module
+ @parent = class_module.parent
+ @parent_name = class_module.parent_name
+
other_document = parse class_module.comment_location
if other_document then
@@ -360,6 +442,18 @@ def merge class_module
end
end
+ @includes.uniq! # clean up
+
+ merge_collections extends, cm.extends, other_files do |add, ext|
+ if add then
+ add_extend ext
+ else
+ @extends.delete ext
+ end
+ end
+
+ @extends.uniq! # clean up
+
merge_collections method_list, cm.method_list, other_files do |add, meth|
if add then
add_method meth
@@ -369,6 +463,8 @@ def merge class_module
end
end
+ merge_sections cm
+
self
end
@@ -391,22 +487,46 @@ def merge_collections mine, other, other_files, &block # :nodoc:
my_things = mine. group_by { |thing| thing.file }
other_things = other.group_by { |thing| thing.file }
- my_things.delete_if do |file, things|
- next false unless other_files.include? file
+ remove_things my_things, other_files, &block
+ add_things my_things, other_things, &block
+ end
- things.each do |thing|
- yield false, thing
- end
+ ##
+ # Merges the comments in this ClassModule with the comments in the other
+ # ClassModule +cm+.
- true
+ def merge_sections cm # :nodoc:
+ my_sections = sections.group_by { |section| section.title }
+ other_sections = cm.sections.group_by { |section| section.title }
+
+ other_files = cm.in_files
+
+ remove_things my_sections, other_files do |_, section|
+ @sections.delete section.title
end
- other_things.each do |file, things|
- my_things[file].each { |thing| yield false, thing } if
- my_things.include?(file)
+ other_sections.each do |group, sections|
+ if my_sections.include? group
+ my_sections[group].each do |my_section|
+ other_section = cm.sections_hash[group]
- things.each do |thing|
- yield true, thing
+ my_comments = my_section.comments
+ other_comments = other_section.comments
+
+ other_files = other_section.in_files
+
+ merge_collections my_comments, other_comments, other_files do |add, comment|
+ if add then
+ my_section.add_comment comment
+ else
+ my_section.remove_comment comment
+ end
+ end
+ end
+ else
+ sections.each do |section|
+ add_section group, section.comments
+ end
end
end
end
@@ -438,11 +558,15 @@ def parse comment_location
when Array then
docs = comment_location.map do |comment, location|
doc = super comment
- doc.file = location.absolute_name
+ doc.file = location
doc
end
RDoc::Markup::Document.new(*docs)
+ when RDoc::Comment then
+ doc = super comment_location.text, comment_location.format
+ doc.file = comment_location.location
+ doc
when RDoc::Markup::Document then
return comment_location
else
@@ -451,10 +575,10 @@ def parse comment_location
end
##
- # Path to this class or module
+ # Path to this class or module for use with HTML generator output.
def path
- http_url RDoc::RDoc.current.generator.class_dir
+ http_url @store.rdoc.generator.class_dir
end
##
@@ -488,21 +612,61 @@ def remove_nodoc_children
modules_hash.each_key do |name|
full_name = prefix + name
- modules_hash.delete name unless RDoc::TopLevel.all_modules_hash[full_name]
+ modules_hash.delete name unless @store.modules_hash[full_name]
end
classes_hash.each_key do |name|
full_name = prefix + name
- classes_hash.delete name unless RDoc::TopLevel.all_classes_hash[full_name]
+ classes_hash.delete name unless @store.classes_hash[full_name]
end
end
+ def remove_things my_things, other_files # :nodoc:
+ my_things.delete_if do |file, things|
+ next false unless other_files.include? file
+
+ things.each do |thing|
+ yield false, thing
+ end
+
+ true
+ end
+ end
+
+ ##
+ # Search record used by RDoc::Generator::JsonIndex
+
+ def search_record
+ [
+ name,
+ full_name,
+ full_name,
+ '',
+ path,
+ '',
+ snippet(@comment_location),
+ ]
+ end
+
+ ##
+ # Sets the store for this class or module and its contained code objects.
+
+ def store= store
+ super
+
+ @attributes .each do |attr| attr.store = store end
+ @constants .each do |const| const.store = store end
+ @includes .each do |incl| incl.store = store end
+ @extends .each do |ext| ext.store = store end
+ @method_list.each do |meth| meth.store = store end
+ end
+
##
# Get the superclass of this class. Attempts to retrieve the superclass
# object, returns the name if it is not known.
def superclass
- RDoc::TopLevel.find_class_named(@superclass) || @superclass
+ @store.find_class_named(@superclass) || @superclass
end
##
@@ -533,7 +697,7 @@ def type
# aliases through a constant.
#
# The aliased module/class is replaced in the children and in
- # RDoc::TopLevel::all_modules_hash or RDoc::TopLevel::all_classes_hash
+ # RDoc::Store#modules_hash or RDoc::Store#classes_hash
# by a copy that has <tt>RDoc::ClassModule#is_alias_for</tt> set to
# the aliased module/class, and this copy is added to <tt>#aliases</tt>
# of the aliased module/class.
@@ -548,16 +712,21 @@ def update_aliases
next unless cm = const.is_alias_for
cm_alias = cm.dup
cm_alias.name = const.name
- cm_alias.parent = self
- cm_alias.full_name = nil # force update for new parent
+
+ # Don't move top-level aliases under Object, they look ugly there
+ unless RDoc::TopLevel === cm_alias.parent then
+ cm_alias.parent = self
+ cm_alias.full_name = nil # force update for new parent
+ end
+
cm_alias.aliases.clear
cm_alias.is_alias_for = cm
if cm.module? then
- RDoc::TopLevel.all_modules_hash[cm_alias.full_name] = cm_alias
+ @store.modules_hash[cm_alias.full_name] = cm_alias
modules_hash[const.name] = cm_alias
else
- RDoc::TopLevel.all_classes_hash[cm_alias.full_name] = cm_alias
+ @store.classes_hash[cm_alias.full_name] = cm_alias
classes_hash[const.name] = cm_alias
end
@@ -574,8 +743,26 @@ def update_aliases
def update_includes
includes.reject! do |include|
mod = include.module
- !(String === mod) && RDoc::TopLevel.all_modules_hash[mod.full_name].nil?
+ !(String === mod) && @store.modules_hash[mod.full_name].nil?
end
+
+ includes.uniq!
+ end
+
+ ##
+ # Deletes from #extends those whose module has been removed from the
+ # documentation.
+ #--
+ # FIXME: like update_includes, extends are not reliably removed
+
+ def update_extends
+ extends.reject! do |ext|
+ mod = ext.module
+
+ !(String === mod) && @store.modules_hash[mod.full_name].nil?
+ end
+
+ extends.uniq!
end
end
View
70 lib/rdoc/code_object.rb
@@ -1,6 +1,3 @@
-require 'rdoc'
-require 'rdoc/text'
-
##
# Base class for the RDoc code tree.
#
@@ -78,19 +75,24 @@ class RDoc::CodeObject
attr_accessor :offset
##
- # Our parent CodeObject
+ # Sets the parent CodeObject
- attr_accessor :parent
+ attr_writer :parent
##
# Did we ever receive a +:nodoc:+ directive?
attr_reader :received_nodoc
##
- # Which section are we in
+ # Set the section this CodeObject is in
- attr_accessor :section
+ attr_writer :section
+
+ ##
+ # The RDoc::Store for this object.
+
+ attr_accessor :store
##
# We are the model of the code, but we know that at some point we will be
@@ -103,11 +105,16 @@ class RDoc::CodeObject
# Creates a new CodeObject that will document itself and its children
def initialize
- @metadata = {}
- @comment = ''
- @parent = nil
- @file = nil
- @full_name = nil
+ @metadata = {}
+ @comment = ''
+ @parent = nil
+ @parent_name = nil # for loading
+ @parent_class = nil # for loading
+ @section = nil
+ @section_title = nil # for loading
+ @file = nil
+ @full_name = nil
+ @store = nil
@document_children = true
@document_self = true
@@ -124,11 +131,11 @@ def comment=(comment)
@comment = case comment
when NilClass then ''
when RDoc::Markup::Document then comment
+ when RDoc::Comment then comment.normalize
else
if comment and not comment.empty? then
normalize_comment comment
else
- # TODO is this sufficient?
# HACK correct fix is to have #initialize create @comment
# with the correct encoding
if String === @comment and
@@ -216,7 +223,7 @@ def file_name
##
# Force the documentation of this object unless documentation
- # has been turned off by :endoc:
+ # has been turned off by :enddoc:
#--
# HACK untested, was assigning to an ivar
@@ -262,6 +269,29 @@ def ignored?
end
##
+ # Our parent CodeObject. The parent may be missing for classes loaded from
+ # legacy RI data stores.
+
+ def parent
+ return @parent if @parent
+ return nil unless @parent_name
+
+ if @parent_class == RDoc::TopLevel then
+ @parent = @store.add_file @parent_name
+ else
+ @parent = @store.find_class_or_module @parent_name
+
+ return @parent if @parent
+
+ begin
+ @parent = @store.load_class @parent_name
+ rescue RDoc::Store::MissingFileError
+ nil
+ end
+ end
+ end
+
+ ##
# File name of our parent
def parent_file_name
@@ -284,8 +314,18 @@ def record_location top_level
end
##
+ # The section this CodeObject is in. Sections allow grouping of constants,
+ # attributes and methods inside a class or module.
+
+ def section
+ return @section if @section
+
+ @section = parent.add_section @section_title if parent
+ end
+
+ ##
# Enable capture of documentation unless documentation has been
- # turned off by :endoc:
+ # turned off by :enddoc:
def start_doc
return if @done_documenting
View
24 lib/rdoc/code_objects.rb
@@ -1,23 +1,5 @@
-# We represent the various high-level code constructs that appear in Ruby
-# programs: classes, modules, methods, and so on.
+# This file was used to load all the RDoc::CodeObject subclasses at once. Now
+# autoload handles this.
-require 'rdoc/code_object'
-require 'rdoc/context'
-require 'rdoc/top_level'
-
-require 'rdoc/class_module'
-require 'rdoc/normal_class'
-require 'rdoc/normal_module'
-require 'rdoc/anon_class'
-require 'rdoc/single_class'
-
-require 'rdoc/any_method'
-require 'rdoc/alias'
-require 'rdoc/ghost_method'
-require 'rdoc/meta_method'
-
-require 'rdoc/attr'
-require 'rdoc/constant'
-require 'rdoc/require'
-require 'rdoc/include'
+require 'rdoc'
View
232 lib/rdoc/comment.rb
@@ -0,0 +1,232 @@
+##
+# A comment holds the text comment for a RDoc::CodeObject and provides a
+# unified way of cleaning it up and parsing it into an RDoc::Markup::Document.
+#
+# Each comment may have a different markup format set by #format=. By default
+# 'rdoc' is used. The :markup: directive tells RDoc which format to use.
+#
+# See RDoc::Markup@Other+directives for instructions on adding an alternate
+# format.
+
+class RDoc::Comment
+
+ include RDoc::Text
+
+ ##
+ # The format of this comment. Defaults to RDoc::Markup
+
+ attr_reader :format
+
+ ##
+ # The RDoc::TopLevel this comment was found in
+
+ attr_accessor :location
+
+ ##
+ # For duck-typing when merging classes at load time
+
+ alias file location # :nodoc:
+
+ ##
+ # The text for this comment
+
+ attr_reader :text
+
+ ##
+ # Overrides the content returned by #parse. Use when there is no #text
+ # source for this comment
+
+ attr_writer :document
+
+ ##
+ # Creates a new comment with +text+ that is found in the RDoc::TopLevel
+ # +location+.
+
+ def initialize text = nil, location = nil
+ @location = location
+ @text = text
+
+ @document = nil
+ @format = 'rdoc'
+ @normalized = false
+ end
+
+ ##
+ #--
+ # TODO deep copy @document
+
+ def initialize_copy copy # :nodoc:
+ @text = copy.text.dup
+ end
+
+ def == other # :nodoc:
+ self.class === other and
+ other.text == @text and other.location == @location
+ end
+
+ ##
+ # Look for a 'call-seq' in the comment to override the normal parameter
+ # handling. The :call-seq: is indented from the baseline. All lines of the
+ # same indentation level and prefix are consumed.
+ #
+ # For example, all of the following will be used as the :call-seq:
+ #
+ # # :call-seq:
+ # # ARGF.readlines(sep=$/) -> array
+ # # ARGF.readlines(limit) -> array
+ # # ARGF.readlines(sep, limit) -> array
+ # #
+ # # ARGF.to_a(sep=$/) -> array
+ # # ARGF.to_a(limit) -> array
+ # # ARGF.to_a(sep, limit) -> array
+
+ def extract_call_seq method
+ # we must handle situations like the above followed by an unindented first
+ # comment. The difficulty is to make sure not to match lines starting
+ # with ARGF at the same indent, but that are after the first description
+ # paragraph.
+ if @text =~ /^\s*:?call-seq:(.*?(?:\S).*?)^\s*$/m then
+ all_start, all_stop = $~.offset(0)
+ seq_start, seq_stop = $~.offset(1)
+
+ # we get the following lines that start with the leading word at the
+ # same indent, even if they have blank lines before
+ if $1 =~ /(^\s*\n)+^(\s*\w+)/m then
+ leading = $2 # ' * ARGF' in the example above
+ re = %r%
+ \A(
+ (^\s*\n)+
+ (^#{Regexp.escape leading}.*?\n)+
+ )+
+ ^\s*$
+ %xm
+
+ if @text[seq_stop..-1] =~ re then
+ all_stop = seq_stop + $~.offset(0).last
+ seq_stop = seq_stop + $~.offset(1).last
+ end
+ end
+
+ seq = @text[seq_start..seq_stop]
+ seq.gsub!(/^\s*(\S|\n)/m, '\1')
+ @text.slice! all_start...all_stop
+
+ method.call_seq = seq.chomp
+
+ elsif @text.sub!(/^\s*:?call-seq:(.*?)(^\s*$|\z)/m, '') then
+ seq = $1
+ seq.gsub!(/^\s*/, '')
+ method.call_seq = seq
+ end
+ #elsif @text.sub!(/\A\/\*\s*call-seq:(.*?)\*\/\Z/, '') then
+ # method.call_seq = $1.strip
+ #end
+
+ method
+ end
+
+ ##
+ # A comment is empty if its text String is empty.
+
+ def empty?
+ @text.empty?
+ end
+
+ ##
+ # HACK dubious
+
+ def force_encoding encoding
+ @text.force_encoding encoding
+ end
+
+ ##
+ # Sets the format of this comment and resets any parsed document
+
+ def format= format
+ @format = format
+ @document = nil
+ end
+
+ def inspect # :nodoc:
+ location = @location ? @location.absolute_name : '(unknown)'
+
+ "#<%s:%x %s %p>" % [self.class, object_id, location, @text]
+ end
+
+ ##
+ # Normalizes the text. See RDoc::Text#normalize_comment for details
+
+ def normalize
+ return self unless @text
+ return self if @normalized # TODO eliminate duplicate normalization
+
+ @text = normalize_comment @text
+
+ @normalized = true
+
+ self
+ end
+
+ ##
+ # Was this text normalized?
+
+ def normalized? # :nodoc:
+ @normalized
+ end
+
+ ##
+ # Parses the comment into an RDoc::Markup::Document. The parsed document is
+ # cached until the text is changed.
+
+ def parse
+ return @document if @document
+
+ @document = super @text, @format
+ @document.file = @location
+ @document
+ end
+
+ ##
+ # Removes private sections from this comment. Private sections are flush to
+ # the comment marker and start with <tt>--</tt> and end with <tt>++</tt>.
+ # For C-style comments, a private marker may not start at the opening of the
+ # comment.
+ #
+ # /*
+ # *--
+ # * private
+ # *++
+ # * public
+ # */
+
+ def remove_private
+ # Workaround for gsub encoding for Ruby 1.9.2 and earlier
+ empty = ''
+ empty.force_encoding @text.encoding if Object.const_defined? :Encoding
+
+ @text = @text.gsub(%r%^\s*([#*]?)--.*?^\s*(\1)\+\+\n?%m, empty)
+ @text = @text.sub(%r%^\s*[#*]?--.*%m, '')
+ end
+
+ ##
+ # Replaces this comment's text with +text+ and resets the parsed document.
+ #
+ # An error is raised if the comment contains a document but no text.
+
+ def text= text
+ raise RDoc::Error, 'replacing document-only comment is not allowed' if
+ @text.nil? and @document
+
+ @document = nil
+ @text = text
+ end
+
+ ##
+ # Returns true if this comment is in TomDoc format.
+
+ def tomdoc?
+ @format == 'tomdoc'
+ end
+
+end
+
View
108 lib/rdoc/constant.rb
@@ -1,16 +1,14 @@
-require 'rdoc/code_object'
-
##
# A constant
class RDoc::Constant < RDoc::CodeObject
+ MARSHAL_VERSION = 0 # :nodoc:
+
##
- # If this constant is an alias for a module or class,
- # this is the RDoc::ClassModule it is an alias for.
- # +nil+ otherwise.
+ # Sets the module or class this is constant is an alias for.
- attr_accessor :is_alias_for
+ attr_writer :is_alias_for
##
# The constant's name
@@ -23,13 +21,22 @@ class RDoc::Constant < RDoc::CodeObject
attr_accessor :value
##
+ # The constant's visibility
+
+ attr_accessor :visibility
+
+ ##
# Creates a new constant with +name+, +value+ and +comment+
def initialize(name, value, comment)
super()
- @name = name
+
+ @name = name
@value = value
+
@is_alias_for = nil
+ @visibility = nil
+
self.comment = comment
end
@@ -59,6 +66,27 @@ def documented?
super or is_alias_for && is_alias_for.documented?
end
+ ##
+ # Full constant name including namespace
+
+ def full_name
+ @full_name ||= "#{parent_name}::#{@name}"
+ end
+
+ ##
+ # The module or class this constant is an alias for
+
+ def is_alias_for
+ case @is_alias_for
+ when String then
+ found = @store.find_class_or_module @is_alias_for
+ @is_alias_for = found if found
+ @is_alias_for
+ else
+ @is_alias_for
+ end
+ end
+
def inspect # :nodoc:
"#<%s:0x%x %s::%s>" % [
self.class, object_id,
@@ -67,12 +95,76 @@ def inspect # :nodoc:
end
##
- # Path to this constant
+ # Dumps this Constant for use by ri. See also #marshal_load
+
+ def marshal_dump
+ alias_name = case found = is_alias_for
+ when RDoc::CodeObject then found.full_name
+ else found
+ end
+
+ [ MARSHAL_VERSION,
+ @name,
+ full_name,
+ @visibility,
+ alias_name,
+ parse(@comment),
+ @file.absolute_name,
+ parent.name,
+ parent.class,
+ section.title,
+ ]
+ end
+
+ ##
+ # Loads this Constant from +array+. For a loaded Constant the following
+ # methods will return cached values:
+ #
+ # * #full_name
+ # * #parent_name
+
+ def marshal_load array
+ initialize array[1], nil, array[5]
+
+ @full_name = array[2]
+ @visibility = array[3]
+ @is_alias_for = array[4]
+ # 5 handled above
+ # 6 handled below
+ @parent_name = array[7]
+ @parent_class = array[8]
+ @section_title = array[9]
+
+ @file = RDoc::TopLevel.new array[6]
+ end
+
+ ##
+ # Path to this constant for use with HTML generator output.
def path
"#{@parent.path}##{@name}"
end
+ def pretty_print q # :nodoc:
+ q.group 2, "[#{self.class.name} #{full_name}", "]" do
+ unless comment.empty? then
+ q.breakable
+ q.text "comment:"
+ q.breakable
+ q.pp @comment
+ end
+ end
+ end
+
+ ##
+ # Sets the store for this class or module and its contained code objects.
+
+ def store= store
+ super
+
+ @file = @store.add_file @file.full_name if @file
+ end
+
def to_s # :nodoc:
parent_name = parent ? parent.full_name : '(unknown)'
if is_alias_for
View
323 lib/rdoc/context.rb
@@ -1,4 +1,4 @@
-require 'rdoc/code_object'
+require 'cgi'
##
# A Context is something that can hold modules, classes, methods, attributes,
@@ -15,6 +15,12 @@ class RDoc::Context < RDoc::CodeObject
TYPES = %w[class instance]
##
+ # If a context has these titles it will be sorted in this order.
+
+ TOMDOC_TITLES = [nil, 'Public', 'Internal', 'Deprecated'] # :nodoc:
+ TOMDOC_TITLES_SORT = TOMDOC_TITLES.sort_by { |title| title.to_s } # :nodoc:
+
+ ##
# Class/module aliases
attr_reader :aliases
@@ -25,6 +31,11 @@ class RDoc::Context < RDoc::CodeObject
attr_reader :attributes
##
+ # Block params to be used in the next MethodAttr parsed under this context
+
+ attr_accessor :block_params
+
+ ##
# Constants defined
attr_reader :constants
@@ -45,6 +56,11 @@ class RDoc::Context < RDoc::CodeObject
attr_reader :includes
##
+ # Modules this context is extended with
+
+ attr_reader :extends
+
+ ##
# Methods defined in this context
attr_reader :method_list
@@ -72,7 +88,7 @@ class RDoc::Context < RDoc::CodeObject
attr_accessor :unmatched_alias_lists
##
- # Aliases that could not eventually be resolved.
+ # Aliases that could not be resolved.
attr_reader :external_aliases
@@ -88,121 +104,14 @@ class RDoc::Context < RDoc::CodeObject
attr_reader :methods_hash
##
- # Hash of registered constants.
+ # Params to be used in the next MethodAttr parsed under this context
- attr_reader :constants_hash
+ attr_accessor :params
##
- # A section of documentation like:
- #
- # # :section: The title
- # # The body
- #
- # Sections can be referenced multiple times and will be collapsed into a
- # single section.
-
- class Section
-
- include RDoc::Text
-
- ##
- # Section comment
-
- attr_reader :comment
-
- ##
- # Context this Section lives in
-
- attr_reader :parent
-
- ##
- # Section title
-
- attr_reader :title
-
- @@sequence = "SEC00000"
-
- ##
- # Creates a new section with +title+ and +comment+
-
- def initialize parent, title, comment
- @parent = parent
- @title = title ? title.strip : title
-
- @@sequence.succ!
- @sequence = @@sequence.dup
-
- @comment = extract_comment comment
- end
-
- ##
- # Sections are equal when they have the same #title
-
- def == other
- self.class === other and @title == other.title
- end
-
- ##
- # Anchor reference for linking to this section
-
- def aref
- title = @title || '[untitled]'
-
- CGI.escape(title).gsub('%', '-').sub(/^-/, '')
- end
-
- ##
- # Appends +comment+ to the current comment separated by a rule.
-
- def comment= comment
- comment = extract_comment comment
-
- return if comment.empty?
-
- if @comment then
- @comment += "\n# ---\n#{comment}"
- else
- @comment = comment
- end
- end
-
- ##
- # Extracts the comment for this section from the original comment block.
- # If the first line contains :section:, strip it and use the rest.
- # Otherwise remove lines up to the line containing :section:, and look
- # for those lines again at the end and remove them. This lets us write
- #
- # # :section: The title
- # # The body
-
- def extract_comment comment
- if comment =~ /^#[ \t]*:section:.*\n/ then
- start = $`
- rest = $'
-
- if start.empty? then
- rest
- else
- rest.sub(/#{start.chomp}\Z/, '')
- end
- else
- comment
- end
- end
-
- def inspect # :nodoc:
- "#<%s:0x%x %p>" % [self.class, object_id, title]
- end
-
- ##
- # Section sequence number (deprecated)
-
- def sequence
- warn "RDoc::Context::Section#sequence is deprecated, use #aref"
- @sequence
- end
+ # Hash of registered constants.
- end
+ attr_reader :constants_hash
##
# Creates an unnamed empty context with public current visibility
@@ -235,15 +144,20 @@ def initialize_methods_etc
@aliases = []
@requires = []
@includes = []
+ @extends = []
@constants = []
@external_aliases = []
# This Hash maps a method name to a list of unmatched aliases (aliases of
# a method not yet encountered).
@unmatched_alias_lists = {}
- @methods_hash = {}
+ @methods_hash = {}
@constants_hash = {}
+
+ @params = nil
+
+ @store ||= nil
end
##
@@ -366,12 +280,12 @@ def add_class class_type, given_name, superclass = '::Object'
if full_name =~ /^(.+)::(\w+)$/ then
name = $2
ename = $1
- enclosing = RDoc::TopLevel.classes_hash[ename] ||
- RDoc::TopLevel.modules_hash[ename]
+ enclosing = @store.classes_hash[ename] || @store.modules_hash[ename]
# HACK: crashes in actionpack/lib/action_view/helpers/form_helper.rb (metaprogramming)
unless enclosing then
# try the given name at top level (will work for the above example)
- enclosing = RDoc::TopLevel.classes_hash[given_name] || RDoc::TopLevel.modules_hash[given_name]
+ enclosing = @store.classes_hash[given_name] ||
+ @store.modules_hash[given_name]
return enclosing if enclosing
# not found: create the parent(s)
names = ename.split('::')
@@ -410,15 +324,15 @@ def add_class class_type, given_name, superclass = '::Object'
end
# did we believe it was a module?
- mod = RDoc::TopLevel.modules_hash.delete superclass
+ mod = @store.modules_hash.delete superclass
upgrade_to_class mod, RDoc::NormalClass, mod.parent if mod
# e.g., Object < Object
superclass = nil if superclass == full_name
end
- klass = RDoc::TopLevel.classes_hash[full_name]
+ klass = @store.classes_hash[full_name]
if klass then
# if TopLevel, it may not be registered in the classes:
@@ -435,7 +349,7 @@ def add_class class_type, given_name, superclass = '::Object'
end
else
# this is a new class
- mod = RDoc::TopLevel.modules_hash.delete full_name
+ mod = @store.modules_hash.delete full_name
if mod then
klass = upgrade_to_class mod, RDoc::NormalClass, enclosing
@@ -445,10 +359,12 @@ def add_class class_type, given_name, superclass = '::Object'
klass = class_type.new name, superclass
enclosing.add_class_or_module(klass, enclosing.classes_hash,
- RDoc::TopLevel.classes_hash)
+ @store.classes_hash)
end
end
+ klass.parent = self
+
klass
end
@@ -463,6 +379,7 @@ def add_class_or_module mod, self_hash, all_hash
mod.section = current_section # TODO declaring context? something is
# wrong here...
mod.parent = self
+ mod.store = @store
unless @done_documenting then
self_hash[mod.name] = mod
@@ -504,13 +421,21 @@ def add_constant constant
# Adds included module +include+ which should be an RDoc::Include
def add_include include
- add_to @includes, include unless
- @includes.map { |i| i.full_name }.include? include.full_name
+ add_to @includes, include
include
end
##
+ # Adds extension module +ext+ which should be an RDoc::Extend
+
+ def add_extend ext
+ add_to @extends, ext
+
+ ext
+ end
+
+ ##
# Adds +method+ if not already there. If it is (as method or attribute),
# updates the comment if it was empty.
@@ -523,6 +448,10 @@ def add_method method
if known then
known.comment = method.comment if known.comment.empty?
+ previously = ", previously in #{known.file}" unless
+ method.file == known.file
+ @store.rdoc.options.warn \
+ "Duplicate method #{known.full_name} in #{method.file}#{previously}"
else
@methods_hash[key] = method
method.visibility = @visibility
@@ -542,9 +471,9 @@ def add_module(class_type, name)
return mod if mod
full_name = child_name name
- mod = RDoc::TopLevel.modules_hash[full_name] || class_type.new(name)
+ mod = @store.modules_hash[full_name] || class_type.new(name)
- add_class_or_module(mod, @modules, RDoc::TopLevel.modules_hash)
+ add_class_or_module mod, @modules, @store.modules_hash
end
##
@@ -554,31 +483,34 @@ def add_module(class_type, name)
def add_module_alias from, name, file
return from if @done_documenting
- to_name = child_name(name)
+ to_name = child_name name
# if we already know this name, don't register an alias:
# see the metaprogramming in lib/active_support/basic_object.rb,
- # where we already know BasicObject as a class when we find
+ # where we already know BasicObject is a class when we find
# BasicObject = BlankSlate
- return from if RDoc::TopLevel.find_class_or_module(to_name)
+ return from if @store.find_class_or_module to_name
- if from.module? then
- RDoc::TopLevel.modules_hash[to_name] = from
- @modules[name] = from
+ to = from.dup
+ to.name = name
+ to.full_name = nil
+
+ if to.module? then
+ @store.modules_hash[to_name] = to
+ @modules[name] = to
else
- RDoc::TopLevel.classes_hash[to_name] = from
- @classes[name] = from
+ @store.classes_hash[to_name] = to
+ @classes[name] = to
end
- # HACK: register a constant for this alias:
- # constant value and comment will be updated after,
- # when the Ruby parser adds the constant
- const = RDoc::Constant.new name, nil, ''
+ # Registers a constant for this alias. The constant value and comment
+ # will be updated later, when the Ruby parser adds the constant
+ const = RDoc::Constant.new name, nil, to.comment
const.record_location file
const.is_alias_for = from
add_constant const
- from
+ to
end
##
@@ -602,9 +534,9 @@ def add_require(require)
#