Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

import RDoc 3.5.3 and fix it for MacRuby.

  • Loading branch information...
commit 31aca7b09884b163e3e710da9cf6849a38422038 1 parent f073ffa
@takaokouji takaokouji authored Laurent Sansonetti committed
Showing with 16,107 additions and 15,049 deletions.
  1. +14 −14 lib/{rdoc/lex → irb}/notifier.rb
  2. +6 −6 lib/{rdoc/lex → irb}/output-method.rb
  3. +23 −23 lib/{rdoc/lex → irb}/slex.rb
  4. +44 −301 lib/rdoc.rb
  5. +0 −232 lib/rdoc/README
  6. +113 −0 lib/rdoc/alias.rb
  7. +12 −0 lib/rdoc/anon_class.rb
  8. +202 −0 lib/rdoc/any_method.rb
  9. +108 −0 lib/rdoc/attr.rb
  10. +430 −0 lib/rdoc/class_module.rb
  11. +243 −0 lib/rdoc/code_object.rb
  12. +18 −1,056 lib/rdoc/code_objects.rb
  13. +86 −0 lib/rdoc/constant.rb
  14. +1,117 −0 lib/rdoc/context.rb
  15. +0 −340 lib/rdoc/diagram.rb
  16. +0 −249 lib/rdoc/dot.rb
  17. +89 −0 lib/rdoc/encoding.rb
  18. +37 −0 lib/rdoc/erbio.rb
  19. +35 −1,077 lib/rdoc/generator.rb
  20. +0 −113 lib/rdoc/generator/chm.rb
  21. +0 −100 lib/rdoc/generator/chm/chm.rb
  22. +390 −0 lib/rdoc/generator/darkfish.rb
  23. +0 −445 lib/rdoc/generator/html.rb
  24. +0 −24 lib/rdoc/generator/html/common.rb
  25. +0 −92 lib/rdoc/generator/html/frameless.rb
  26. +0 −150 lib/rdoc/generator/html/hefss.rb
  27. +0 −769 lib/rdoc/generator/html/html.rb
  28. +0 −151 lib/rdoc/generator/html/kilmer.rb
  29. +0 −427 lib/rdoc/generator/html/kilmerfactory.rb
  30. +0 −122 lib/rdoc/generator/html/one_page_html.rb
  31. +206 −0 lib/rdoc/generator/markup.rb
  32. +43 −184 lib/rdoc/generator/ri.rb
  33. 0  lib/rdoc/generator/template/darkfish/.document
  34. +319 −0 lib/rdoc/generator/template/darkfish/classpage.rhtml
  35. +124 −0 lib/rdoc/generator/template/darkfish/filepage.rhtml
  36. BIN  lib/rdoc/generator/template/darkfish/images/brick.png
  37. BIN  lib/rdoc/generator/template/darkfish/images/brick_link.png
  38. BIN  lib/rdoc/generator/template/darkfish/images/bug.png
  39. BIN  lib/rdoc/generator/template/darkfish/images/bullet_black.png
  40. BIN  lib/rdoc/generator/template/darkfish/images/bullet_toggle_minus.png
  41. BIN  lib/rdoc/generator/template/darkfish/images/bullet_toggle_plus.png
  42. BIN  lib/rdoc/generator/template/darkfish/images/date.png
  43. BIN  lib/rdoc/generator/template/darkfish/images/find.png
  44. BIN  lib/rdoc/generator/template/darkfish/images/loadingAnimation.gif
  45. BIN  lib/rdoc/generator/template/darkfish/images/macFFBgHack.png
  46. BIN  lib/rdoc/generator/template/darkfish/images/package.png
  47. BIN  lib/rdoc/generator/template/darkfish/images/page_green.png
  48. BIN  lib/rdoc/generator/template/darkfish/images/page_white_text.png
  49. BIN  lib/rdoc/generator/template/darkfish/images/page_white_width.png
  50. BIN  lib/rdoc/generator/template/darkfish/images/plugin.png
  51. BIN  lib/rdoc/generator/template/darkfish/images/ruby.png
  52. BIN  lib/rdoc/generator/template/darkfish/images/tag_green.png
  53. BIN  lib/rdoc/generator/template/darkfish/images/wrench.png
  54. BIN  lib/rdoc/generator/template/darkfish/images/wrench_orange.png
  55. BIN  lib/rdoc/generator/template/darkfish/images/zoom.png
  56. +64 −0 lib/rdoc/generator/template/darkfish/index.rhtml
  57. +116 −0 lib/rdoc/generator/template/darkfish/js/darkfish.js
  58. +32 −0 lib/rdoc/generator/template/darkfish/js/jquery.js
  59. +114 −0 lib/rdoc/generator/template/darkfish/js/quicksearch.js
  60. +10 −0 lib/rdoc/generator/template/darkfish/js/thickbox-compressed.js
  61. +759 −0 lib/rdoc/generator/template/darkfish/rdoc.css
  62. +0 −81 lib/rdoc/generator/texinfo.rb
  63. +0 −44 lib/rdoc/generator/texinfo/class.texinfo.erb
  64. +0 −6 lib/rdoc/generator/texinfo/file.texinfo.erb
  65. +0 −6 lib/rdoc/generator/texinfo/method.texinfo.erb
  66. +0 −28 lib/rdoc/generator/texinfo/texinfo.erb
  67. +0 −117 lib/rdoc/generator/xml.rb
  68. +0 −113 lib/rdoc/generator/xml/rdf.rb
  69. +0 −123 lib/rdoc/generator/xml/xml.rb
  70. +8 −0 lib/rdoc/ghost_method.rb
  71. +100 −0 lib/rdoc/include.rb
  72. +2 −0  lib/rdoc/known_classes.rb
  73. +0 −3  lib/rdoc/lex/README.txt
  74. +491 −276 lib/rdoc/markup.rb
  75. +119 −51 lib/rdoc/markup/attribute_manager.rb
  76. +27 −0 lib/rdoc/markup/blank_line.rb
  77. +78 −0 lib/rdoc/markup/document.rb
  78. +139 −0 lib/rdoc/markup/formatter.rb
  79. +689 −0 lib/rdoc/markup/formatter_test_case.rb
  80. +0 −337 lib/rdoc/markup/fragments.rb
  81. +20 −0 lib/rdoc/markup/heading.rb
  82. +44 −8 lib/rdoc/markup/inline.rb
  83. +0 −153 lib/rdoc/markup/lines.rb
  84. +81 −0 lib/rdoc/markup/list.rb
  85. +86 −0 lib/rdoc/markup/list_item.rb
  86. +14 −0 lib/rdoc/markup/paragraph.rb
  87. +483 −0 lib/rdoc/markup/parser.rb
  88. +151 −0 lib/rdoc/markup/pre_process.rb
  89. +0 −75 lib/rdoc/markup/preprocess.rb
  90. +69 −0 lib/rdoc/markup/raw.rb
  91. +20 −0 lib/rdoc/markup/rule.rb
  92. +116 −0 lib/rdoc/markup/text_formatter_test_case.rb
  93. +84 −0 lib/rdoc/markup/to_ansi.rb
  94. +80 −0 lib/rdoc/markup/to_bs.rb
  95. +0 −185 lib/rdoc/markup/to_flow.rb
  96. +186 −266 lib/rdoc/markup/to_html.rb
  97. +124 −69 lib/rdoc/markup/to_html_crossref.rb
  98. +0 −328 lib/rdoc/markup/to_latex.rb
  99. +292 −0 lib/rdoc/markup/to_rdoc.rb
  100. +38 −16 lib/rdoc/markup/to_test.rb
  101. +0 −69 lib/rdoc/markup/to_texinfo.rb
  102. +114 −0 lib/rdoc/markup/to_tt_only.rb
  103. +45 −0 lib/rdoc/markup/verbatim.rb
  104. +8 −0 lib/rdoc/meta_method.rb
  105. +353 −0 lib/rdoc/method_attr.rb
  106. +71 −0 lib/rdoc/normal_class.rb
  107. +66 −0 lib/rdoc/normal_module.rb
  108. +450 −320 lib/rdoc/options.rb
  109. +88 −30 lib/rdoc/parser.rb
  110. +600 −269 lib/rdoc/parser/c.rb
  111. +0 −1,835 lib/rdoc/parser/f95.rb
  112. +0 −165 lib/rdoc/parser/perl.rb
  113. +775 −1,819 lib/rdoc/parser/ruby.rb
  114. +160 −0 lib/rdoc/parser/ruby_tools.rb
  115. +22 −11 lib/rdoc/parser/simple.rb
  116. +409 −202 lib/rdoc/rdoc.rb
  117. +53 −0 lib/rdoc/require.rb
  118. +10 −0 lib/rdoc/ri.rb
  119. +0 −187 lib/rdoc/ri/cache.rb
  120. +0 −156 lib/rdoc/ri/descriptions.rb
  121. +0 −392 lib/rdoc/ri/display.rb
  122. +824 −387 lib/rdoc/ri/driver.rb
  123. +2 −613 lib/rdoc/ri/formatter.rb
  124. +82 −46 lib/rdoc/ri/paths.rb
  125. +0 −106 lib/rdoc/ri/reader.rb
  126. +265 −0 lib/rdoc/ri/store.rb
  127. +0 −79 lib/rdoc/ri/util.rb
  128. +0 −68 lib/rdoc/ri/writer.rb
  129. +1,293 −0 lib/rdoc/ruby_lex.rb
  130. +416 −0 lib/rdoc/ruby_token.rb
  131. +23 −0 lib/rdoc/single_class.rb
  132. +380 −57 lib/rdoc/stats.rb
  133. +51 −0 lib/rdoc/stats/normal.rb
  134. +59 −0 lib/rdoc/stats/quiet.rb
  135. +45 −0 lib/rdoc/stats/verbose.rb
  136. +327 −0 lib/rdoc/task.rb
  137. +0 −64 lib/rdoc/template.rb
  138. +314 −0 lib/rdoc/text.rb
  139. +28 −11 lib/rdoc/{tokenstream.rb → token_stream.rb}
  140. +439 −0 lib/rdoc/top_level.rb
  141. +6 −3 test_vm.rb
  142. +34 −0 vm.cpp
View
28 lib/rdoc/lex/notifier.rb → lib/irb/notifier.rb
@@ -1,31 +1,31 @@
#
-# notifier.rb - output methods used by irb
-# $Release Version: 0.9.5$
-# $Revision: 16810 $
+# notifier.rb - output methods used by irb
+# $Release Version: 0.9.6$
+# $Revision$
# by Keiju ISHITSUKA(keiju@ruby-lang.org)
#
# --
#
-#
+#
#
require "e2mmap"
-require "rdoc/lex/output-method"
+require "irb/output-method"
module IRB
module Notifier
extend Exception2MessageMapper
- def_exception :ErrUndefinedNotifier,
+ def_exception :ErrUndefinedNotifier,
"undefined notifier level: %d is specified"
- def_exception :ErrUnrecognizedLevel,
+ def_exception :ErrUnrecognizedLevel,
"unrecognized notifier level: %s is specified"
def def_notifier(prefix = "", output_method = StdioOutputMethod.new)
CompositeNotifier.new(prefix, output_method)
end
module_function :def_notifier
-
- class AbstructNotifier
+
+ class AbstractNotifier
def initialize(prefix, base_notifier)
@prefix = prefix
@base_notifier = base_notifier
@@ -72,7 +72,7 @@ def exec_if
end
end
- class CompositeNotifier<AbstructNotifier
+ class CompositeNotifier<AbstractNotifier
def initialize(prefix, base_notifier)
super
@@ -93,7 +93,7 @@ def def_notifier(level, prefix = "")
def level_notifier=(value)
case value
- when AbstructNotifier
+ when AbstractNotifier
@level_notifier = value
when Integer
l = @notifiers[value]
@@ -107,12 +107,12 @@ def level_notifier=(value)
alias level= level_notifier=
end
- class LeveledNotifier<AbstructNotifier
+ class LeveledNotifier<AbstractNotifier
include Comparable
def initialize(base, level, prefix)
super(prefix, base)
-
+
@level = level
end
@@ -121,7 +121,7 @@ def initialize(base, level, prefix)
def <=>(other)
@level <=> other.level
end
-
+
def notify?
@base_notifier.level >= self
end
View
12 lib/rdoc/lex/output-method.rb → lib/irb/output-method.rb
@@ -1,12 +1,12 @@
#
-# output-method.rb - optput methods used by irb
-# $Release Version: 0.9.5$
-# $Revision: 14912 $
+# output-method.rb - output methods used by irb
+# $Release Version: 0.9.6$
+# $Revision$
# by Keiju ISHITSUKA(keiju@ruby-lang.org)
#
# --
#
-#
+#
#
require "e2mmap"
@@ -16,7 +16,7 @@ module IRB
# StdioOutputMethod
class OutputMethod
- @RCS_ID='-$Id: output-method.rb 14912 2008-01-06 15:49:38Z akr $-'
+ @RCS_ID='-$Id$-'
def print(*opts)
IRB.fail NotImplementError, "print"
@@ -39,7 +39,7 @@ def printf(format, *opts)
# <minimum field width> (\*|\*[1-9][0-9]*\$|[1-9][0-9]*)
# <precision>.(\*|\*[1-9][0-9]*\$|[1-9][0-9]*|)?
# #<length modifier>(hh|h|l|ll|L|q|j|z|t)
- # <conversion specifier>[diouxXeEfgGcsb%]
+ # <conversion specifier>[diouxXeEfgGcsb%]
def parse_printf_format(format, opts)
return format, opts if $1.size % 2 == 1
end
View
46 lib/rdoc/lex/slex.rb → lib/irb/slex.rb
@@ -1,20 +1,20 @@
#
# irb/slex.rb - simple lex analyzer
-# $Release Version: 0.9.5$
-# $Revision: 16810 $
+# $Release Version: 0.9.6$
+# $Revision$
# by Keiju ISHITSUKA(keiju@ruby-lang.org)
#
# --
#
-#
+#
#
require "e2mmap"
-require "rdoc/lex/notifier"
+require "irb/notifier"
module IRB
class SLex
- @RCS_ID='-$Id: slex.rb 16810 2008-06-04 09:37:38Z matz $-'
+ @RCS_ID='-$Id$-'
extend Exception2MessageMapper
def_exception :ErrNodeNothing, "node nothing"
@@ -24,20 +24,20 @@ class SLex
D_WARN = DOUT::def_notifier(1, "Warn: ")
D_DEBUG = DOUT::def_notifier(2, "Debug: ")
D_DETAIL = DOUT::def_notifier(4, "Detail: ")
-
+
DOUT.level = Notifier::D_NOMSG
def initialize
@head = Node.new("")
end
-
+
def def_rule(token, preproc = nil, postproc = nil, &block)
D_DETAIL.pp token
postproc = block if block_given?
- node = create(token, preproc, postproc)
+ create(token, preproc, postproc)
end
-
+
def def_rules(*tokens, &block)
if block_given?
p = block
@@ -46,18 +46,18 @@ def def_rules(*tokens, &block)
def_rule(token, nil, p)
end
end
-
+
def preproc(token, proc)
node = search(token)
node.preproc=proc
end
-
- #$BMW%A%'%C%/(B?
+
+ #$BMW%A%'%C%/(B?
def postproc(token)
node = search(token, proc)
node.postproc=proc
end
-
+
def search(token)
@head.search(token.split(//))
end
@@ -65,7 +65,7 @@ def search(token)
def create(token, preproc = nil, postproc = nil)
@head.create_subnode(token.split(//), preproc, postproc)
end
-
+
def match(token)
case token
when Array
@@ -78,14 +78,14 @@ def match(token)
D_DETAIL.exec_if{D_DEATIL.printf "match end: %s:%s\n", ret, token.inspect}
ret
end
-
+
def inspect
format("<SLex: @head = %s>", @head.inspect)
end
#----------------------------------------------------------------------
#
- # class Node -
+ # class Node -
#
#----------------------------------------------------------------------
class Node
@@ -99,7 +99,7 @@ def initialize(preproc = nil, postproc = nil)
attr_accessor :preproc
attr_accessor :postproc
-
+
def search(chrs, opt = nil)
return self if chrs.empty?
ch = chrs.shift
@@ -114,7 +114,7 @@ def search(chrs, opt = nil)
end
end
end
-
+
def create_subnode(chrs, preproc = nil, postproc = nil)
if chrs.empty?
if @postproc
@@ -127,7 +127,7 @@ def create_subnode(chrs, preproc = nil, postproc = nil)
end
return self
end
-
+
ch = chrs.shift
if node = @Tree[ch]
if chrs.empty?
@@ -161,7 +161,7 @@ def create_subnode(chrs, preproc = nil, postproc = nil)
# chrs: String
# character array
# io must have getc()/ungetc(); and ungetc() must be
- # able to be called arbitrary number of times.
+ # able to be called arbitrary number of times.
#
def match(chrs, op = "")
D_DETAIL.print "match>: ", chrs, "op:", op, "\n"
@@ -254,14 +254,14 @@ def match_io(io, op = "")
print "1: ", tr.inspect, "\n"
tr.def_rule("==") {print "==\n"}
print "2: ", tr.inspect, "\n"
-
+
print "case 1:\n"
print tr.match("="), "\n"
print "case 2:\n"
print tr.match("=="), "\n"
print "case 3:\n"
print tr.match("=>"), "\n"
-
+
when "2"
tr = SLex.new
print "0: ", tr.inspect, "\n"
@@ -269,7 +269,7 @@ def match_io(io, op = "")
print "1: ", tr.inspect, "\n"
tr.def_rule("==", proc{false}) {print "==\n"}
print "2: ", tr.inspect, "\n"
-
+
print "case 1:\n"
print tr.match("="), "\n"
print "case 2:\n"
View
345 lib/rdoc.rb
@@ -1,5 +1,7 @@
$DEBUG_RDOC = nil
+# :main: README.txt
+
##
# = \RDoc - Ruby Documentation System
#
@@ -16,13 +18,16 @@
# == Roadmap
#
# * If you want to use RDoc to create documentation for your Ruby source files,
-# read on.
-# * If you want to include extensions written in C, see RDoc::Parser::C
+# read the summary below, and refer to <tt>rdoc --help</tt> for command line
+# usage, and RDoc::Markup for a detailed description of RDoc's markup.
+# * If you want to generate documentation for extensions written in C, see
+# RDoc::Parser::C
# * If you want to drive RDoc programmatically, see RDoc::RDoc.
-# * If you want to use the library to format text blocks into HTML, have a look
-# at RDoc::Markup.
-# * If you want to try writing your own HTML output template, see
-# RDoc::Generator::HTML
+# * 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 try writing your own output generator see RDoc::Generator.
#
# == Summary
#
@@ -31,6 +36,7 @@
# % rdoc [options] [names...]
#
# For an up-to-date option summary, type
+#
# % rdoc --help
#
# A typical use might be to generate documentation for a package of Ruby
@@ -46,7 +52,7 @@
# index page contain the documentation for the primary file. In our
# case, we could type
#
-# % rdoc --main rdoc.rb
+# % rdoc --main README.txt
#
# You'll find information on the various formatting tricks you can use
# in comment blocks in the documentation this generates.
@@ -58,278 +64,9 @@
# markers). If directory names are passed to RDoc, they are scanned
# recursively for C and Ruby source files only.
#
-# == \Options
-# rdoc can be passed a variety of command-line options. In addition,
-# options can be specified via the +RDOCOPT+ environment variable, which
-# functions similarly to the +RUBYOPT+ environment variable.
-#
-# % export RDOCOPT="-S"
-#
-# will make rdoc default to inline method source code. Command-line options
-# always will override those in +RDOCOPT+.
-#
-# Run
-#
-# % rdoc --help
-#
-# for full details on rdoc's options.
-#
-# Here are some of the most commonly used options.
-# [-d, --diagram]
-# Generate diagrams showing modules and
-# classes. You need dot V1.8.6 or later to
-# use the --diagram option correctly. Dot is
-# available from http://graphviz.org
-#
-# [-S, --inline-source]
-# Show method source code inline, rather than via a popup link.
-#
-# [-T, --template=NAME]
-# Set the template used when generating output.
-#
-# == Documenting Source Code
-#
-# Comment blocks can be written fairly naturally, either using +#+ on
-# successive lines of the comment, or by including the comment in
-# a =begin/=end block. If you use the latter form, the =begin 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 containing
-# a <tt>--</tt>. 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 a
-# <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.
-#
-# 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.
-#
-# == \Markup
-#
-# * 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.
-#
-# * If a paragraph starts with a "*", "-", or with "<digit>.", 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
-#
-# * 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
-#
-# A minor variation on labeled lists uses two colons to separate the
-# label from the list body:
-#
-# cat:: a small furry mammal
-# that seems to sleep a lot
-#
-# ant:: a little insect that is known
-# to enjoy picnics
-#
-# This latter style guarantees that the list bodies' left margins are
-# aligned: think of them as a two column table.
-#
-# * Any line that starts to the right of the current margin is treated
-# as verbatim text. This is useful for code listings. The example of a
-# list above is also verbatim text.
-#
-# * A line starting with an equals sign (=) is treated as a
-# heading. Level one headings have one equals sign, level two headings
-# have two,and so on.
-#
-# * 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)
-#
-# * 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:
-#
-# [\*word*] displays word in a *bold* font
-# [\_word_] displays word in an _emphasized_ font
-# [\+word+] displays word in a +code+ font
-#
-# General markup affects text between a start delimiter and and end
-# delimiter. Not surprisingly, these delimiters look like HTML markup.
-#
-# [\<b>text...</b>] displays word in a *bold* font
-# [\<em>text...</em>] displays word in an _emphasized_ font
-# [\\<i>text...</i>] displays word in an <i>italicized</i> font
-# [\<tt>text...</tt>] displays word in a +code+ font
-#
-# 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. This only works for
-# simple markup, not HTML-style markup.
-#
-# * Hyperlinks to the web starting http:, mailto:, ftp:, or www. are
-# recognized. An HTTP url that references an external image file is
-# converted into an inline <IMG..>. Hyperlinks starting 'link:' are
-# assumed to refer to local files whose path is relative to the --op
-# directory.
-#
-# Hyperlinks can also be of the form <tt>label</tt>[url], in which
-# case the 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<em>]</em>.
-#
-# == Directives
-#
-# [+:nodoc:+ / +:nodoc:+ all]
-# 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 is global across all files for the class or module
-# to which it applies, so use +:stopdoc:+/+:startdoc:+ to suppress
-# documentation only for a particular set of methods, etc.
-#
-# [+: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.
-#
-# [+:notnew:+]
-# 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:+ modifier stops this. Remember that +initialize+ is private,
-# so you won't see the documentation unless you use the +-a+ command line
-# option.
-#
-# Comment blocks can contain other directives:
-#
-# [<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.
-# # ----------------------------------------
-#
-# [+: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.
-#
-# [+:include:+ _filename_]
-# \Include the contents of the named file at this point. 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).
-#
-# [+:enddoc:+]
-# Document nothing further at the current level.
-#
-# [+:main:+ _name_]
-# Equivalent to the <tt>--main</tt> command line parameter.
-#
-# [+: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 entire class or module.
-#
# == Other stuff
#
-# RDoc is currently being maintained by Eric Hodel <drbrain@segment7.net>
+# RDoc is currently being maintained by Eric Hodel <drbrain@segment7.net>.
#
# Dave Thomas <dave@pragmaticprogrammer.com> is the original author of RDoc.
#
@@ -338,27 +75,6 @@
# * 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.
-#
-# * Code to diagram classes and modules was written by Sergey A Yanovitsky
-# (Jah) of Enticla.
-#
-# * Charset patch from MoonWolf.
-#
-# * Rich Kilmer wrote the kilmer.rb output template.
-#
-# * Dan Brickley led the design of the RDF format.
-#
-# == License
-#
-# RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers. It
-# is free software, and may be redistributed under the terms specified
-# in the README file of the Ruby distribution.
-#
-# == Warranty
-#
-# This software is provided "as is" and without any express or implied
-# warranties, including, without limitation, the implied warranties of
-# merchantibility and fitness for a particular purpose.
module RDoc
@@ -367,12 +83,24 @@ module RDoc
class Error < RuntimeError; end
- RDocError = Error # :nodoc:
+ 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 = "2.2.2"
+ VERSION = '3.5.3'
+
+ ##
+ # Method visibilities
+
+ VISIBILITIES = [:public, :protected, :private]
##
# Name of the dotfile that contains the description of files to be processed
@@ -380,14 +108,29 @@ class Error < RuntimeError; end
DOT_DOC_FILENAME = ".document"
+ ##
+ # General RDoc modifiers
+
GENERAL_MODIFIERS = %w[nodoc].freeze
+ ##
+ # RDoc modifiers for classes
+
CLASS_MODIFIERS = GENERAL_MODIFIERS
- ATTR_MODIFIERS = GENERAL_MODIFIERS
+ ##
+ # RDoc modifiers for attributes
+
+ ATTR_MODIFIERS = GENERAL_MODIFIERS
+
+ ##
+ # RDoc modifiers for constants
CONSTANT_MODIFIERS = GENERAL_MODIFIERS
+ ##
+ # RDoc modifiers for methods
+
METHOD_MODIFIERS = GENERAL_MODIFIERS +
%w[arg args yield yields notnew not-new not_new doc]
View
232 lib/rdoc/README
@@ -1,232 +0,0 @@
-= RDOC - Ruby Documentation System
-
-This package contains RDoc and RDoc::Markup. RDoc is an application that
-produces documentation for one or more Ruby source files. We work similarly to
-JavaDoc, parsing the source, and extracting the definition for classes,
-modules, and methods (along with includes and requires). We associate with
-these optional documentation contained in the immediately preceding comment
-block, and then render the result using a pluggable output formatter.
-RDoc::Markup is a library 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.
-
-== Roadmap
-
-* If you want to use RDoc to create documentation for your Ruby source files,
- read on.
-* If you want to include extensions written in C, see RDoc::C_Parser
-* For information on the various markups available in comment blocks, see
- RDoc::Markup.
-* If you want to drive RDoc programmatically, see RDoc::RDoc.
-* If you want to use the library to format text blocks into HTML, have a look
- at RDoc::Markup.
-* If you want to try writing your own HTML output template, see
- RDoc::Generator::HTML
-
-== Summary
-
-Once installed, you can create documentation using the 'rdoc' command
-(the command is 'rdoc.bat' under Windows)
-
- % rdoc [options] [names...]
-
-Type "rdoc --help" for an up-to-date option summary.
-
-A typical use might be to generate documentation for a package of Ruby
-source (such as rdoc itself).
-
- % rdoc
-
-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'.
-
-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
-
- % rdoc --main rdoc.rb
-
-You'll find information on the various formatting tricks you can use
-in comment blocks in the documentation this generates.
-
-RDoc uses file extensions to determine how to process each file. File names
-ending +.rb+ and <tt>.rbw</tt> 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.
-
-= Markup
-
-For information on how to make lists, hyperlinks, & etc. with RDoc, see
-RDoc::Markup.
-
-Comment blocks can be written fairly naturally, either using '#' on successive
-lines of the comment, or by including the comment in an =begin/=end block. If
-you use the latter form, the =begin 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 containing '+#--+'.
-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 '+#+++'.
-
- ##
- # 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, source files, and any method names containing an underscore
-or preceded by a hash character are automatically hyperlinked from comment text
-to their description.
-
-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.
-
-== Directives
-
-[+:nodoc:+ / +:nodoc:+ all]
- Don't include this element in the documentation. For classes
- and modules, the methods, aliases, constants, and attributes
- directly within the affected class or module will also 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 +MyModule::Input+ will be documented.
-
-[+:doc:+]
- Force a method or attribute to be documented even if it wouldn't otherwise
- be. Useful if, for example, you want to include documentation of a
- particular private method.
-
-[+:notnew:+]
- 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: modifier
- stops this. Remember that #initialize is protected, so you won't see the
- documentation unless you use the -a command line option.
-
-Comment blocks can contain other directives:
-
-[+:section: title+]
- 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.
- # ----------------------------------------
-
-[+: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.
-
-[+:include:+ _filename_]
- Include the contents of the named file at this point. 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 --title command line
- parameter. (The command line parameter overrides any :title: directive in
- the source).
-
-[+:enddoc:+]
- Document nothing further at the current level.
-
-[+:main:+ _name_]
- Equivalent to the --main command line parameter.
-
-[+: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 entire class or module.
-
-= Other stuff
-
-Author:: Dave Thomas <dave@pragmaticprogrammer.com>
-
-== 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.
-
-* Code to diagram classes and modules was written by Sergey A Yanovitsky
- (Jah) of Enticla.
-
-* Charset patch from MoonWolf.
-
-* Rich Kilmer wrote the kilmer.rb output template.
-
-* Dan Brickley led the design of the RDF format.
-
-== License
-
-RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers. It
-is free software, and may be redistributed under the terms specified
-in the README file of the Ruby distribution.
-
-== Warranty
-
-This software is provided "as is" and without any express or implied
-warranties, including, without limitation, the implied warranties of
-merchantibility and fitness for a particular purpose.
-
View
113 lib/rdoc/alias.rb
@@ -0,0 +1,113 @@
+require 'rdoc/code_object'
+
+##
+# Represent an alias, which is an old_name/new_name pair associated with a
+# particular context
+#--
+# TODO implement Alias as a proxy to a method/attribute, inheriting from
+# MethodAttr
+
+class RDoc::Alias < RDoc::CodeObject
+
+ ##
+ # Aliased method's name
+
+ attr_reader :new_name
+
+ alias name new_name
+
+ ##
+ # Aliasee method's name
+
+ attr_reader :old_name
+
+ ##
+ # Is this an alias declared in a singleton context?
+
+ attr_accessor :singleton
+
+ ##
+ # Source file token stream
+
+ attr_reader :text
+
+ ##
+ # Creates a new Alias with a token stream of +text+ that aliases +old_name+
+ # to +new_name+, has +comment+ and is a +singleton+ context.
+
+ def initialize(text, old_name, new_name, comment, singleton = false)
+ super()
+
+ @text = text
+ @singleton = singleton
+ @old_name = old_name
+ @new_name = new_name
+ self.comment = comment
+ end
+
+ ##
+ # Order by #singleton then #new_name
+
+ def <=>(other)
+ [@singleton ? 0 : 1, new_name] <=> [other.singleton ? 0 : 1, other.new_name]
+ end
+
+ ##
+ # HTML fragment reference for this alias
+
+ def aref
+ type = singleton ? 'c' : 'i'
+ "#alias-#{type}-#{html_name}"
+ end
+
+ ##
+ # Full old name including namespace
+
+ def full_old_name
+ @full_name || "#{parent.name}#{pretty_old_name}"
+ end
+
+ ##
+ # HTML id-friendly version of +#new_name+.
+
+ def html_name
+ CGI.escape(@new_name.gsub('-', '-2D')).gsub('%','-').sub(/^-/, '')
+ end
+
+ def inspect # :nodoc:
+ parent_name = parent ? parent.name : '(unknown)'
+ "#<%s:0x%x %s.alias_method %s, %s>" % [
+ self.class, object_id,
+ parent_name, @old_name, @new_name,
+ ]
+ end
+
+ ##
+ # '::' for the alias of a singleton method/attribute, '#' for instance-level.
+
+ def name_prefix
+ singleton ? '::' : '#'
+ end
+
+ ##
+ # Old name with prefix '::' or '#'.
+
+ def pretty_old_name
+ "#{singleton ? '::' : '#'}#{@old_name}"
+ end
+
+ ##
+ # New name with prefix '::' or '#'.
+
+ def pretty_new_name
+ "#{singleton ? '::' : '#'}#{@new_name}"
+ end
+
+ alias pretty_name pretty_new_name
+
+ def to_s # :nodoc:
+ "alias: #{self.new_name} -> #{self.pretty_old_name} in: #{parent}"
+ end
+
+end
+
View
12 lib/rdoc/anon_class.rb
@@ -0,0 +1,12 @@
+require 'rdoc/class_module'
+
+##
+# An anonymous class like:
+#
+# c = Class.new do end
+#
+# AnonClass is currently not used.
+
+class RDoc::AnonClass < RDoc::ClassModule
+end
+
View
202 lib/rdoc/any_method.rb
@@ -0,0 +1,202 @@
+require 'rdoc/method_attr'
+require 'rdoc/token_stream'
+
+##
+# AnyMethod is the base class for objects representing methods
+
+class RDoc::AnyMethod < RDoc::MethodAttr
+
+ MARSHAL_VERSION = 0 # :nodoc:
+
+ ##
+ # Don't rename \#initialize to \::new
+
+ attr_accessor :dont_rename_initialize
+
+ ##
+ # The C function that implements this method (if it was defined in a C file)
+
+ attr_accessor :c_function
+
+ ##
+ # Different ways to call this method
+
+ attr_accessor :call_seq
+
+ ##
+ # Parameters for this method
+
+ attr_accessor :params
+
+ include RDoc::TokenStream
+
+ ##
+ # Creates a new AnyMethod with a token stream +text+ and +name+
+
+ def initialize text, name
+ super
+
+ @c_function = nil
+ @dont_rename_initialize = false
+ @token_stream = nil
+ end
+
+ ##
+ # Adds +an_alias+ as an alias for this method in +context+.
+
+ def add_alias(an_alias, context = nil )
+ method = self.class.new an_alias.text, an_alias.new_name
+
+ method.record_location an_alias.file
+ method.singleton = self.singleton
+ method.params = self.params
+ method.visibility = self.visibility
+ method.comment = an_alias.comment
+ method.is_alias_for = self
+ @aliases << method
+ context.add_method( method ) if context
+ method
+ end
+
+ ##
+ # Prefix for +aref+ is 'method'.
+
+ def aref_prefix
+ 'method'
+ end
+
+ ##
+ # The call_seq or the param_seq with method name, if there is no call_seq.
+ #
+ # Use this for displaying a method's argument lists.
+
+ def arglists
+ if @call_seq then
+ @call_seq
+ elsif @params then
+ "#{name}#{param_seq}"
+ end
+ end
+
+ ##
+ # Dumps this AnyMethod for use by ri. See also #marshal_load
+
+ def marshal_dump
+ aliases = @aliases.map do |a|
+ [a.full_name, parse(a.comment)]
+ end
+
+ [ MARSHAL_VERSION,
+ @name,
+ full_name,
+ @singleton,
+ @visibility,
+ parse(@comment),
+ @call_seq,
+ @block_params,
+ aliases,
+ @params,
+ ]
+ end
+
+ ##
+ # Loads this AnyMethod from +array+. For a loaded AnyMethod the following
+ # methods will return cached values:
+ #
+ # * #full_name
+ # * #parent_name
+
+ def marshal_load(array)
+ @dont_rename_initialize = nil
+ @is_alias_for = nil
+ @token_stream = nil
+ @aliases = []
+
+ @name = array[1]
+ @full_name = array[2]
+ @singleton = array[3]
+ @visibility = array[4]
+ @comment = array[5]
+ @call_seq = array[6]
+ @block_params = array[7]
+ @params = array[9]
+
+ @parent_name = if @full_name =~ /#/ then
+ $`
+ else
+ name = @full_name.split('::')
+ name.pop
+ name.join '::'
+ end
+
+ array[8].each do |new_name, comment|
+ add_alias RDoc::Alias.new(nil, @name, new_name, comment, @singleton)
+ end
+ end
+
+ ##
+ # Method name
+ #
+ # If the method has no assigned name, it extracts it from #call_seq.
+
+ def name
+ return @name if @name
+
+ @name = @call_seq[/^.*?\.(\w+)/, 1] || @call_seq if @call_seq
+ end
+
+ ##
+ # A list of this method's method and yield parameters. +call-seq+ params
+ # are preferred over parsed method and block params.
+
+ def param_list
+ if @call_seq then
+ params = @call_seq.split("\n").last
+ params = params.sub(/.*?\((.*)\)/, '\1')
+ params = params.sub(/(\{|do)\s*\|([^|]*)\|.*/, ',\2')
+ elsif @params then
+ params = @params.sub(/\((.*)\)/, '\1')
+
+ params << ",#{@block_params}" if @block_params
+ elsif @block_params then
+ params = @block_params
+ else
+ return []
+ end
+
+ params.gsub(/\s+/, '').split ','
+ end
+
+ ##
+ # Pretty parameter list for this method. If the method's parameters were
+ # given by +call-seq+ it is preferred over the parsed values.
+
+ def param_seq
+ if @call_seq then
+ params = @call_seq.split("\n").last
+ params = params.sub(/[^( ]+/, '')
+ params = params.sub(/(\|[^|]+\|)\s*\.\.\.\s*(end|\})/, '\1 \2')
+ else
+ params = @params.gsub(/\s*\#.*/, '')
+ params = params.tr("\n", " ").squeeze(" ")
+ params = "(#{params})" unless params[0] == ?(
+ end
+
+ if @block_params then
+ # If this method has explicit block parameters, remove any explicit
+ # &block
+ params.sub!(/,?\s*&\w+/, '')
+
+ block = @block_params.gsub(/\s*\#.*/, '')
+ block = block.tr("\n", " ").squeeze(" ")
+ if block[0] == ?(
+ block.sub!(/^\(/, '').sub!(/\)/, '')
+ end
+ params << " { |#{block}| ... }"
+ end
+
+ params
+ end
+
+end
+
View
108 lib/rdoc/attr.rb
@@ -0,0 +1,108 @@
+require 'rdoc/method_attr'
+
+##
+# An attribute created by \#attr, \#attr_reader, \#attr_writer or
+# \#attr_accessor
+
+class RDoc::Attr < RDoc::MethodAttr
+
+ MARSHAL_VERSION = 1 # :nodoc:
+
+ ##
+ # Is the attribute readable ('R'), writable ('W') or both ('RW')?
+
+ attr_accessor :rw
+
+ ##
+ # Creates a new Attr with body +text+, +name+, read/write status +rw+ and
+ # +comment+. +singleton+ marks this as a class attribute.
+
+ def initialize(text, name, rw, comment, singleton = false)
+ super text, name
+
+ @rw = rw
+ @singleton = singleton
+ self.comment = comment
+ end
+
+ ##
+ # Attributes are equal when their names, singleton and rw are identical
+
+ def == other
+ self.class == other.class and
+ self.name == other.name and
+ self.rw == other.rw and
+ self.singleton == other.singleton
+ end
+
+ ##
+ # Add +an_alias+ as an attribute in +context+.
+
+ def add_alias(an_alias, context)
+ new_attr = self.class.new(self.text, an_alias.new_name, self.rw,
+ self.comment, self.singleton)
+
+ new_attr.record_location an_alias.file
+ new_attr.visibility = self.visibility
+ new_attr.is_alias_for = self
+ @aliases << new_attr
+ context.add_attribute new_attr
+ new_attr
+ end
+
+ ##
+ # The #aref prefix for attributes
+
+ def aref_prefix
+ 'attribute'
+ end
+
+ ##
+ # Returns attr_reader, attr_writer or attr_accessor as appropriate.
+
+ def definition
+ case @rw
+ when 'RW' then 'attr_accessor'
+ when 'R' then 'attr_reader'
+ when 'W' then 'attr_writer'
+ end
+ end
+
+ ##
+ # Dumps this Attr for use by ri. See also #marshal_load
+
+ def marshal_dump
+ [ MARSHAL_VERSION,
+ @name,
+ full_name,
+ @rw,
+ @visibility,
+ parse(@comment),
+ singleton,
+ ]
+ end
+
+ ##
+ # Loads this Attr from +array+. For a loaded Attr the following
+ # methods will return cached values:
+ #
+ # * #full_name
+ # * #parent_name
+
+ def marshal_load array
+ @name = array[1]
+ @full_name = array[2]
+ @rw = array[3]
+ @visibility = array[4]
+ @comment = array[5]
+ @singleton = array[6] || false # MARSHAL_VERSION == 0
+
+ @parent_name = @full_name
+ end
+
+ def to_s # :nodoc:
+ "#{definition} #{name} in: #{parent}"
+ end
+
+end
+
View
430 lib/rdoc/class_module.rb
@@ -0,0 +1,430 @@
+require 'rdoc/context'
+
+##
+# ClassModule is the base class for objects representing either a class or a
+# module.
+
+class RDoc::ClassModule < RDoc::Context
+
+ MARSHAL_VERSION = 0 # :nodoc:
+
+ ##
+ # Constants that are aliases for this class or module
+
+ attr_accessor :constant_aliases
+
+ attr_accessor :diagram # :nodoc:
+
+ ##
+ # Class or module this constant is an alias for
+
+ attr_accessor :is_alias_for
+
+ ##
+ # Return a RDoc::ClassModule of class +class_type+ that is a copy
+ # of module +module+. Used to promote modules to classes.
+
+ def self.from_module(class_type, mod)
+ klass = class_type.new(mod.name)
+ klass.comment = mod.comment
+ klass.parent = mod.parent
+ klass.section = mod.section
+ klass.viewer = mod.viewer
+
+ klass.attributes.concat mod.attributes
+ klass.method_list.concat mod.method_list
+ klass.aliases.concat mod.aliases
+ klass.external_aliases.concat mod.external_aliases
+ klass.constants.concat mod.constants
+ klass.includes.concat mod.includes
+
+ klass.methods_hash.update mod.methods_hash
+ klass.constants_hash.update mod.constants_hash
+
+ klass.current_section = mod.current_section
+ klass.in_files.concat mod.in_files
+ klass.sections.concat mod.sections
+ klass.unmatched_alias_lists = mod.unmatched_alias_lists
+ klass.current_section = mod.current_section
+ klass.visibility = mod.visibility
+
+ klass.classes_hash.update mod.classes_hash
+ klass.modules_hash.update mod.modules_hash
+ klass.metadata.update mod.metadata
+
+ klass.document_self = mod.received_nodoc ? nil : mod.document_self
+ klass.document_children = mod.document_children
+ klass.force_documentation = mod.force_documentation
+ klass.done_documenting = mod.done_documenting
+
+ # update the parent of all children
+
+ (klass.attributes +
+ klass.method_list +
+ klass.aliases +
+ klass.external_aliases +
+ klass.constants +
+ klass.includes +
+ klass.classes +
+ klass.modules).each do |obj|
+ obj.parent = klass
+ obj.full_name = nil
+ end
+
+ klass
+ end
+
+ ##
+ # Creates a new ClassModule with +name+ with optional +superclass+
+ #
+ # This is a constructor for subclasses, and must never be called directly.
+
+ def initialize(name, superclass = nil)
+ @constant_aliases = []
+ @diagram = nil
+ @is_alias_for = nil
+ @name = name
+ @superclass = superclass
+ super()
+ end
+
+ ##
+ # Ancestors list for this ClassModule: the list of included modules
+ # (classes will add their superclass if any).
+ #
+ # Returns the included classes or modules, not the includes
+ # themselves. The returned values are either String or
+ # RDoc::NormalModule instances (see RDoc::Include#module).
+ #
+ # The values are returned in reverse order of their inclusion,
+ # which is the order suitable for searching methods/attributes
+ # in the ancestors. The superclass, if any, comes last.
+
+ def ancestors
+ includes.map { |i| i.module }.reverse
+ end
+
+ ##
+ # Clears the comment. Used by the ruby parser.
+
+ def clear_comment
+ @comment = ''
+ end
+
+ ##
+ # Appends +comment+ to the current comment, but separated by a rule. Works
+ # more like <tt>+=</tt>.
+
+ def comment= comment
+ return if comment.empty?
+
+ comment = normalize_comment comment
+ comment = "#{@comment}\n---\n#{comment}" unless
+ @comment.empty?
+
+ super
+ end
+
+ ##
+ # Prepares this ClassModule for use by a generator.
+ #
+ # See RDoc::TopLevel::complete
+
+ def complete min_visibility
+ update_aliases
+ remove_nodoc_children
+ update_includes
+ remove_invisible min_visibility
+ end
+
+ ##
+ # Looks for a symbol in the #ancestors. See Context#find_local_symbol.
+
+ def find_ancestor_local_symbol symbol
+ ancestors.each do |m|
+ next if m.is_a?(String)
+ res = m.find_local_symbol(symbol)
+ return res if res
+ end
+
+ nil
+ end
+
+ ##
+ # Finds a class or module with +name+ in this namespace or its descendants
+
+ def find_class_named name
+ return self if full_name == name
+ return self if @name == name
+
+ @classes.values.find do |klass|
+ next if klass == self
+ klass.find_class_named name
+ end
+ end
+
+ ##
+ # Return the fully qualified name of this class or module
+
+ def full_name
+ @full_name ||= if RDoc::ClassModule === @parent then
+ "#{@parent.full_name}::#{@name}"
+ else
+ @name
+ end
+ end
+
+ def marshal_dump # :nodoc:
+ # TODO must store the singleton attribute
+ attrs = attributes.sort.map do |attr|
+ [attr.name, attr.rw]
+ end
+
+ method_types = methods_by_type.map do |type, visibilities|
+ visibilities = visibilities.map do |visibility, methods|
+ method_names = methods.map do |method|
+ method.name
+ end
+
+ [visibility, method_names.uniq]
+ end
+
+ [type, visibilities]
+ end
+
+ [ MARSHAL_VERSION,
+ @name,
+ full_name,
+ @superclass,
+ parse(@comment),
+ attrs,
+ constants.map do |const|
+ [const.name, parse(const.comment)]
+ end,
+ includes.map do |incl|
+ [incl.name, parse(incl.comment)]
+ end,
+ method_types,
+ ]
+ end
+
+ def marshal_load array # :nodoc:
+ # TODO must restore the singleton attribute
+ initialize_methods_etc
+ @document_self = true
+ @done_documenting = false
+ @current_section = nil
+ @parent = nil
+ @visibility = nil
+
+ @name = array[1]
+ @full_name = array[2]
+ @superclass = array[3]
+ @comment = array[4]
+
+ array[5].each do |name, rw|
+ add_attribute RDoc::Attr.new(nil, name, rw, nil)
+ end
+
+ array[6].each do |name, comment|
+ add_constant RDoc::Constant.new(name, nil, comment)
+ end
+
+ array[7].each do |name, comment|
+ add_include RDoc::Include.new(name, comment)
+ end
+
+ array[8].each do |type, visibilities|
+ visibilities.each do |visibility, methods|
+ @visibility = visibility
+
+ methods.each do |name|
+ method = RDoc::AnyMethod.new nil, name
+ method.singleton = true if type == 'class'
+ add_method method
+ end
+ end
+ end
+ end
+
+ ##
+ # Merges +class_module+ into this ClassModule
+
+ def merge class_module
+ comment = class_module.comment
+
+ if comment then
+ document = parse @comment
+
+ comment.parts.concat document.parts
+
+ @comment = comment
+ end
+
+ class_module.each_attribute do |attr|
+ if match = attributes.find { |a| a.name == attr.name } then
+ match.rw = [match.rw, attr.rw].compact.join
+ else
+ add_attribute attr
+ end
+ end
+
+ class_module.each_constant do |const|
+ add_constant const
+ end
+
+ class_module.each_include do |incl|
+ add_include incl
+ end
+
+ class_module.each_method do |meth|
+ add_method meth
+ end
+ end
+
+ ##
+ # Does this object represent a module?
+
+ def module?
+ false
+ end
+
+ ##
+ # Allows overriding the initial name.
+ #
+ # Used for modules and classes that are constant aliases.
+
+ def name= new_name
+ @name = new_name
+ end
+
+ ##
+ # Path to this class or module
+
+ def path
+ http_url RDoc::RDoc.current.generator.class_dir
+ end
+
+ ##
+ # Name to use to generate the url:
+ # modules and classes that are aliases for another
+ # module or class return the name of the latter.
+
+ def name_for_path
+ is_alias_for ? is_alias_for.full_name : full_name
+ end
+
+ ##
+ # Returns the classes and modules that are not constants
+ # aliasing another class or module. For use by formatters
+ # only (caches its result).
+
+ def non_aliases
+ @non_aliases ||= classes_and_modules.reject { |cm| cm.is_alias_for }
+ end
+
+ ##
+ # Updates the child modules or classes of class/module +parent+ by
+ # deleting the ones that have been removed from the documentation.
+ #
+ # +parent_hash+ is either <tt>parent.modules_hash</tt> or
+ # <tt>parent.classes_hash</tt> and +all_hash+ is ::all_modules_hash or
+ # ::all_classes_hash.
+
+ def remove_nodoc_children
+ prefix = self.full_name + '::'
+
+ modules_hash.each_key do |name|
+ full_name = prefix + name
+ modules_hash.delete name unless RDoc::TopLevel.all_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]
+ 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
+ end
+
+ ##
+ # Set the superclass of this class to +superclass+
+
+ def superclass=(superclass)
+ raise NoMethodError, "#{full_name} is a module" if module?
+ @superclass = superclass
+ end
+
+ def to_s # :nodoc:
+ if is_alias_for then
+ "#{self.class.name} #{self.full_name} -> #{is_alias_for}"
+ else
+ super
+ end
+ end
+
+ ##
+ # 'module' or 'class'
+
+ def type
+ module? ? 'module' : 'class'
+ end
+
+ ##
+ # Updates the child modules & classes by replacing the ones that are
+ # 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
+ # 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.
+ #
+ # Formatters can use the #non_aliases method to retrieve children that
+ # are not aliases, for instance to list the namespace content, since
+ # the aliased modules are included in the constants of the class/module,
+ # that are listed separately.
+
+ def update_aliases
+ constants.each do |const|
+ 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
+ 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
+ modules_hash[const.name] = cm_alias
+ else
+ RDoc::TopLevel.all_classes_hash[cm_alias.full_name] = cm_alias
+ classes_hash[const.name] = cm_alias
+ end
+
+ cm.aliases << cm_alias
+ end
+ end
+
+ ##
+ # Deletes from #includes those whose module has been removed from the
+ # documentation.
+ #--
+ # FIXME: includes are not reliably removed, see _possible_bug test case
+
+ def update_includes
+ includes.reject! do |include|
+ mod = include.module
+ !(String === mod) && RDoc::TopLevel.all_modules_hash[mod.full_name].nil?
+ end
+ end
+
+end
+
View
243 lib/rdoc/code_object.rb
@@ -0,0 +1,243 @@
+require 'rdoc'
+require 'rdoc/text'
+
+##
+# Base class for the RDoc code tree.
+#
+# We contain the common stuff for contexts (which are containers) and other
+# elements (methods, attributes and so on)
+#
+# Here's the tree of the CodeObject subclasses:
+#
+# * RDoc::Context
+# * RDoc::TopLevel
+# * RDoc::ClassModule
+# * RDoc::AnonClass (never used so far)
+# * RDoc::NormalClass
+# * RDoc::NormalModule
+# * RDoc::SingleClass
+# * RDoc::MethodAttr
+# * RDoc::Attr
+# * RDoc::AnyMethod
+# * RDoc::GhostMethod
+# * RDoc::MetaMethod
+# * RDoc::Alias
+# * RDoc::Constant
+# * RDoc::Require
+# * RDoc::Include
+
+class RDoc::CodeObject
+
+ include RDoc::Text
+
+ ##
+ # Our comment
+
+ attr_reader :comment
+
+ ##
+ # Do we document our children?
+
+ attr_reader :document_children
+
+ ##
+ # Do we document ourselves?
+
+ attr_reader :document_self
+
+ ##
+ # Are we done documenting (ie, did we come across a :enddoc:)?
+
+ attr_reader :done_documenting
+
+ ##
+ # Which file this code object was defined in
+
+ attr_reader :file
+
+ ##
+ # Force documentation of this CodeObject
+
+ attr_reader :force_documentation
+
+ ##
+ # Line in #file where this CodeObject was defined
+
+ attr_accessor :line
+
+ ##
+ # Hash of arbitrary metadata for this CodeObject
+
+ attr_reader :metadata
+
+ ##
+ # Offset in #file where this CodeObject was defined
+ #--
+ # TODO character or byte?
+
+ attr_accessor :offset
+
+ ##
+ # Our parent CodeObject
+
+ attr_accessor :parent
+
+ ##
+ # Did we ever receive a +:nodoc:+ directive?
+
+ attr_reader :received_nodoc
+
+ ##
+ # Which section are we in
+
+ attr_accessor :section
+
+ ##
+ # We are the model of the code, but we know that at some point we will be
+ # worked on by viewers. By implementing the Viewable protocol, viewers can
+ # associated themselves with these objects.
+
+ attr_accessor :viewer
+
+ ##
+ # Creates a new CodeObject that will document itself and its children
+
+ def initialize
+ @metadata = {}
+ @comment = ''
+ @parent = nil
+ @file = nil
+ @full_name = nil
+
+ @document_children = true
+ @document_self = true
+ @done_documenting = false
+ @force_documentation = false
+ @received_nodoc = false
+ end
+
+ ##
+ # Replaces our comment with +comment+, unless it is empty.
+
+ def comment=(comment)
+ @comment = case comment
+ when NilClass then ''
+ when RDoc::Markup::Document then comment
+ 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 Object.const_defined? :Encoding and @comment.empty? then
+ @comment.force_encoding comment.encoding
+ end
+ @comment
+ end
+ end
+ end
+
+ ##
+ # Enables or disables documentation of this CodeObject's children unless it
+ # has been turned off by :enddoc:
+
+ def document_children=(document_children)
+ @document_children = document_children unless @done_documenting
+ end
+
+ ##
+ # Enables or disables documentation of this CodeObject unless it has been
+ # turned off by :enddoc:. If the argument is +nil+ it means the
+ # documentation is turned off by +:nodoc:+.
+
+ def document_self=(document_self)
+ return if @done_documenting
+
+ @document_self = document_self
+ @received_nodoc = true if document_self.nil?
+ end
+
+ ##
+ # Does this object have a comment with content or is #received_nodoc true?
+
+ def documented?
+ @received_nodoc or !@comment.empty?
+ end
+
+ ##
+ # Turns documentation on/off, and turns on/off #document_self
+ # and #document_children.
+ #
+ # Once documentation has been turned off (by +:enddoc:+),
+ # the object will refuse to turn #document_self or
+ # #document_children on, so +:doc:+ and +:start_doc:+ directives
+ # will have no effect in the current file.
+
+ def done_documenting=(value)
+ @done_documenting = value
+ @document_self = !value
+ @document_children = @document_self
+ end
+
+ ##
+ # Force the documentation of this object unless documentation
+ # has been turned off by :endoc:
+ #--
+ # HACK untested, was assigning to an ivar
+
+ def force_documentation=(value)
+ @force_documentation = value unless @done_documenting
+ end
+
+ ##
+ # Sets the full_name overriding any computed full name.
+ #
+ # Set to +nil+ to clear RDoc's cached value
+
+ def full_name= full_name
+ @full_name = full_name
+ end
+
+ ##
+ # File name of our parent
+
+ def parent_file_name
+ @parent ? @parent.base_name : '(unknown)'
+ end
+
+ ##
+ # Name of our parent
+
+ def parent_name
+ @parent ? @parent.full_name : '(unknown)'
+ end
+
+ ##
+ # Records the RDoc::TopLevel (file) where this code object was defined
+
+ def record_location top_level
+ @file = top_level
+ end
+
+ ##
+ # Enable capture of documentation unless documentation has been
+ # turned off by :endoc:
+
+ def start_doc
+ return if @done_documenting
+
+ @document_self = true
+ @document_children = true
+ end
+
+ ##
+ # Disable capture of documentation
+
+ def stop_doc
+ @document_self = false
+ @document_children = false
+ end
+
+end
+
View
1,074 lib/rdoc/code_objects.rb
@@ -1,1061 +1,23 @@
-# We represent the various high-level code constructs that appear
-# in Ruby programs: classes, modules, methods, and so on.
+# We represent the various high-level code constructs that appear in Ruby
+# programs: classes, modules, methods, and so on.
-require 'rdoc/tokenstream'
+require 'rdoc/code_object'
+require 'rdoc/context'
+require 'rdoc/top_level'
-module RDoc
+require 'rdoc/class_module'
+require 'rdoc/normal_class'
+require 'rdoc/normal_module'
+require 'rdoc/anon_class'
+require 'rdoc/single_class'
- ##
- # We contain the common stuff for contexts (which are containers) and other
- # elements (methods, attributes and so on)
+require 'rdoc/any_method'
+require 'rdoc/alias'
+require 'rdoc/ghost_method'
+require 'rdoc/meta_method'
- class CodeObject
+require 'rdoc/attr'
+require 'rdoc/constant'
+require 'rdoc/require'
+require 'rdoc/include'
- attr_accessor :parent
-
- # We are the model of the code, but we know that at some point
- # we will be worked on by viewers. By implementing the Viewable
- # protocol, viewers can associated themselves with these objects.
-
- attr_accessor :viewer
-
- # are we done documenting (ie, did we come across a :enddoc:)?
-
- attr_accessor :done_documenting
-
- # Which section are we in
-
- attr_accessor :section
-
- # do we document ourselves?
-
- attr_reader :document_self
-
- def initialize
- @document_self = true
- @document_children = true
- @force_documentation = false
- @done_documenting = false
- end
-
- def document_self=(val)
- @document_self = val
- if !val
- remove_methods_etc
- end
- end
-
- # set and cleared by :startdoc: and :enddoc:, this is used to toggle
- # the capturing of documentation
- def start_doc
- @document_self = true
- @document_children = true
- end
-
- def stop_doc
- @document_self = false
- @document_children = false
- end
-
- # do we document ourselves and our children
-
- attr_reader :document_children
-
- def document_children=(val)
- @document_children = val
- if !val
- remove_classes_and_modules
- end
- end
-
- # Do we _force_ documentation, even is we wouldn't normally show the entity
- attr_accessor :force_documentation
-
- def parent_file_name
- @parent ? @parent.file_base_name : '(unknown)'
- end
-
- def parent_name
- @parent ? @parent.name : '(unknown)'
- end
-
- # Default callbacks to nothing, but this is overridden for classes
- # and modules
- def remove_classes_and_modules
- end
-
- def remove_methods_etc
- end
-
- # Access the code object's comment
- attr_reader :comment
-
- # Update the comment, but don't overwrite a real comment with an empty one
- def comment=(comment)
- @comment = comment unless comment.empty?
- end
-
- # There's a wee trick we pull. Comment blocks can have directives that
- # override the stuff we extract during the parse. So, we have a special
- # class method, attr_overridable, that lets code objects list
- # those directives. Wehn a comment is assigned, we then extract
- # out any matching directives and update our object
-
- def self.attr_overridable(name, *aliases)
- @overridables ||= {}
-
- attr_accessor name
-
- aliases.unshift name
- aliases.each do |directive_name|
- @overridables[directive_name.to_s] = name
- end
- end
-
- end
-
- ##
- # A Context is something that can hold modules, classes, methods,
- # attributes, aliases, requires, and includes. Classes, modules, and files
- # are all Contexts.
-
- class Context < CodeObject
-
- attr_reader :aliases
- attr_reader :attributes
- attr_reader :constants
- attr_reader :current_section
- attr_reader :in_files
- attr_reader :includes
- attr_reader :method_list
- attr_reader :name
- attr_reader :requires
- attr_reader :sections
- attr_reader :visibility
-
- class Section
- attr_reader :title, :comment, :sequence
-
- @@sequence = "SEC00000"
-
- def initialize(title, comment)
- @title = title
- @@sequence.succ!
- @sequence = @@sequence.dup
- @comment = nil
- set_comment(comment)
- end
-
- def ==(other)
- self.class === other and @sequence == other.sequence
- end
-
- def inspect
- "#<%s:0x%x %s %p>"