rdoc 2.3.0 → 2.4.0

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.

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

Files changed (81) hide show
  1. data.tar.gz.sig +0 -0
  2. data/.autotest +14 -0
  3. data/History.txt +27 -0
  4. data/Manifest.txt +29 -9
  5. data/Rakefile +2 -0
  6. data/bin/rdoc +13 -2
  7. data/lib/rdoc.rb +11 -3
  8. data/lib/rdoc/alias.rb +54 -0
  9. data/lib/rdoc/anon_class.rb +10 -0
  10. data/lib/rdoc/any_method.rb +190 -0
  11. data/lib/rdoc/attr.rb +79 -0
  12. data/lib/rdoc/cache.rb +11 -2
  13. data/lib/rdoc/class_module.rb +87 -0
  14. data/lib/rdoc/code_object.rb +152 -0
  15. data/lib/rdoc/code_objects.rb +18 -1118
  16. data/lib/rdoc/constant.rb +36 -0
  17. data/lib/rdoc/context.rb +712 -0
  18. data/lib/rdoc/diagram.rb +8 -8
  19. data/lib/rdoc/generator.rb +3 -1140
  20. data/lib/rdoc/generator/darkfish.rb +107 -133
  21. data/lib/rdoc/generator/markup.rb +194 -0
  22. data/lib/rdoc/generator/ri.rb +4 -2
  23. data/lib/rdoc/generator/template/darkfish/classpage.rhtml +92 -113
  24. data/lib/rdoc/generator/template/darkfish/filepage.rhtml +33 -35
  25. data/lib/rdoc/generator/template/darkfish/index.rhtml +22 -15
  26. data/lib/rdoc/ghost_method.rb +8 -0
  27. data/lib/rdoc/include.rb +39 -0
  28. data/lib/rdoc/markup/attribute_manager.rb +46 -0
  29. data/lib/rdoc/markup/formatter.rb +11 -0
  30. data/lib/rdoc/markup/fragments.rb +42 -2
  31. data/lib/rdoc/markup/inline.rb +29 -4
  32. data/lib/rdoc/markup/lines.rb +4 -0
  33. data/lib/rdoc/markup/preprocess.rb +4 -0
  34. data/lib/rdoc/markup/to_flow.rb +27 -1
  35. data/lib/rdoc/markup/to_html.rb +33 -33
  36. data/lib/rdoc/markup/to_html_crossref.rb +4 -11
  37. data/lib/rdoc/markup/to_latex.rb +31 -31
  38. data/lib/rdoc/markup/to_test.rb +3 -0
  39. data/lib/rdoc/markup/to_texinfo.rb +18 -14
  40. data/lib/rdoc/meta_method.rb +8 -0
  41. data/lib/rdoc/normal_class.rb +18 -0
  42. data/lib/rdoc/normal_module.rb +34 -0
  43. data/lib/rdoc/options.rb +26 -159
  44. data/lib/rdoc/parser/c.rb +16 -8
  45. data/lib/rdoc/parser/ruby.rb +16 -10
  46. data/lib/rdoc/parser/simple.rb +1 -1
  47. data/lib/rdoc/rdoc.rb +50 -34
  48. data/lib/rdoc/require.rb +32 -0
  49. data/lib/rdoc/ri/descriptions.rb +1 -1
  50. data/lib/rdoc/ri/driver.rb +4 -4
  51. data/lib/rdoc/ri/formatter.rb +70 -32
  52. data/lib/rdoc/single_class.rb +8 -0
  53. data/lib/rdoc/top_level.rb +232 -0
  54. data/test/test_rdoc_any_method.rb +10 -0
  55. data/test/test_rdoc_code_object.rb +80 -0
  56. data/test/test_rdoc_constant.rb +15 -0
  57. data/test/test_rdoc_context.rb +250 -0
  58. data/test/test_rdoc_include.rb +17 -0
  59. data/test/test_rdoc_markup.rb +13 -2
  60. data/test/test_rdoc_markup_to_html.rb +22 -0
  61. data/test/test_rdoc_markup_to_html_crossref.rb +50 -115
  62. data/test/test_rdoc_normal_module.rb +26 -0
  63. data/test/test_rdoc_parser_c.rb +33 -0
  64. data/test/test_rdoc_parser_ruby.rb +54 -36
  65. data/test/test_rdoc_require.rb +25 -0
  66. data/test/test_rdoc_ri_default_display.rb +2 -1
  67. data/test/test_rdoc_ri_html_formatter.rb +141 -0
  68. data/test/test_rdoc_top_level.rb +85 -0
  69. data/test/xref_data.rb +46 -0
  70. data/test/xref_test_case.rb +48 -0
  71. metadata +42 -13
  72. metadata.gz.sig +0 -0
  73. data/lib/rdoc/generator/html.rb +0 -456
  74. data/lib/rdoc/generator/html/common.rb +0 -24
  75. data/lib/rdoc/generator/html/html.rb +0 -769
  76. data/lib/rdoc/generator/html/one_page_html.rb +0 -122
  77. data/lib/rdoc/generator/xml.rb +0 -124
  78. data/lib/rdoc/generator/xml/rdf.rb +0 -113
  79. data/lib/rdoc/generator/xml/xml.rb +0 -123
  80. data/lib/rdoc/parser/f95.rb +0 -1835
  81. data/lib/rdoc/template.rb +0 -68
data/lib/rdoc/generator/template/darkfish/index.rhtml CHANGED
@@ -4,13 +4,13 @@
4
4
 
5
5
  <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
6
6
  <head>
7
- <meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
7
+ <meta content="text/html; charset=<%= @options.charset %>" http-equiv="Content-Type" />
8
8
 
9
- <title><%= h options.title %></title>
9
+ <title><%= h @options.title %></title>
10
10
 
11
11
  <link type="text/css" media="screen" href="rdoc.css" rel="stylesheet" />
12
12
 
13
- <script src="js/jquery.js" type="text/javascript" charset="utf-8"></script>
13
+ <script src="js/jquery.js" type="text/javascript" charset="utf-8"></script>
14
14
  <script src="js/thickbox-compressed.js" type="text/javascript" charset="utf-8"></script>
15
15
  <script src="js/quicksearch.js" type="text/javascript" charset="utf-8"></script>
16
16
  <script src="js/darkfish.js" type="text/javascript" charset="utf-8"></script>
@@ -19,38 +19,45 @@
19
19
  <body class="indexpage">
20
20
 
21
21
  <% $stderr.sync = true %>
22
- <h1><%= h options.title %></h1>
22
+ <h1><%= h @options.title %></h1>
23
23
 
24
- <% if options.main_page && files.key?( options.main_page ) %>
24
+ <% if @options.main_page && main_page = @files.find { |f| f.full_name == @options.main_page } %>
25
25
  <div id="main">
26
- <%= files[ options.main_page ][:description].sub(%r{^\s*<h1.*?/h1>}i, '') %>
26
+ <%= main_page.description.sub(%r{^\s*<h1.*?/h1>}i, '') %>
27
27
  </div>
28
28
  <% else %>
29
- <p>This is the API documentation for '<%= options.title %>'.</p>
29
+ <p>This is the API documentation for '<%= @options.title %>'.</p>
30
30
  <% end %>
31
31
 
32
- <% simple_files = files.select {|_, file| file[:parser] == RDoc::Parser::Simple } %>
32
+ <% simple_files = @files.select {|tl| tl.parser == RDoc::Parser::Simple } %>
33
33
  <% unless simple_files.empty? then %>
34
34
  <h2>Files</h2>
35
35
  <ul>
36
- <% simple_files.sort_by {|name,_| name }.each do |name, file| %>
37
- <li class="file"><a href="<%= file[:short_name] %>.html"><%= h file[:short_name] %></a></li>
36
+ <% simple_files.sort.each do |file| %>
37
+ <li class="file"><a href="<%= file.base_name %>.html"><%= h file.base_name %></a></li>
38
38
  <% end %>
39
39
  </ul>
40
40
  <% end %>
41
41
 
42
42
  <h2>Classes/Modules</h2>
43
43
  <ul>
44
- <% modsort.each do |classname| %>
45
- <% classdata = classes[classname] %>
46
- <li class="<%= classdata[:classmod].downcase %>"><a
47
- href="<%= classdata[:full_name].gsub( /::/, '/' ) + '.html' %>"><%= classdata[:full_name] %></a></li>
44
+ <% @modsort.each do |klass| %>
45
+ <li class="<%= klass.type %>"><a href="<%= klass.path %>"><%= klass.full_name %></a></li>
46
+ <% end %>
47
+ </ul>
48
+
49
+ <h2>Methods</h2>
50
+ <ul>
51
+ <% RDoc::TopLevel.all_classes_and_modules.map do |mod|
52
+ mod.method_list
53
+ end.flatten.sort.each do |method| %>
54
+ <li><a href="<%= method.path %>"><%= method.pretty_name %> &mdash; <%= method.parent.full_name %></a></li>
48
55
  <% end %>
49
56
  </ul>
50
57
 
51
58
  <div id="validator-badges">
52
59
  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
53
- <p><small>Generated with the <a href="http://deveiate.org/projects/Darkfish-Rdoc/">Darkfish
60
+ <p><small>Generated with the <a href="http://deveiate.org/projects/Darkfish-Rdoc/">Darkfish
54
61
  Rdoc Generator</a> <%= RDoc::Generator::Darkfish::VERSION %></small>.</p>
55
62
  </div>
56
63
  </body>
data/lib/rdoc/ghost_method.rb ADDED
@@ -0,0 +1,8 @@
1
+ require 'rdoc/any_method'
2
+
3
+ ##
4
+ # GhostMethod represents a method referenced only by a comment
5
+
6
+ class RDoc::GhostMethod < RDoc::AnyMethod
7
+ end
8
+
data/lib/rdoc/include.rb ADDED
@@ -0,0 +1,39 @@
1
+ require 'rdoc/code_object'
2
+
3
+ ##
4
+ # A Module include in a class with \#include
5
+
6
+ class RDoc::Include < RDoc::CodeObject
7
+
8
+ ##
9
+ # Name of included module
10
+
11
+ attr_accessor :name
12
+
13
+ ##
14
+ # Creates a new Include for +name+ with +comment+
15
+
16
+ def initialize(name, comment)
17
+ super()
18
+ @name = name
19
+ self.comment = comment
20
+ end
21
+
22
+ def inspect # :nodoc:
23
+ "#<%s:0x%x %s.include %s>" % [
24
+ self.class,
25
+ object_id,
26
+ parent_name, @name,
27
+ ]
28
+ end
29
+
30
+ ##
31
+ # Attempts to locate the included module object. Returns the name if not
32
+ # known.
33
+
34
+ def module
35
+ RDoc::TopLevel.find_module_named(@name) || @name
36
+ end
37
+
38
+ end
39
+
data/lib/rdoc/markup/attribute_manager.rb CHANGED
@@ -1,7 +1,13 @@
1
1
  require 'rdoc/markup/inline'
2
2
 
3
+ ##
4
+ # Manages changes of attributes in a block of text
5
+
3
6
  class RDoc::Markup::AttributeManager
4
7
 
8
+ ##
9
+ # The NUL character
10
+
5
11
  NULL = "\000".freeze
6
12
 
7
13
  ##
@@ -96,6 +102,9 @@ class RDoc::Markup::AttributeManager
96
102
  end
97
103
  end
98
104
 
105
+ ##
106
+ # Converts HTML tags to RDoc attributes
107
+
99
108
  def convert_html(str, attrs)
100
109
  tags = HTML_TAGS.keys.join '|'
101
110
 
@@ -108,6 +117,9 @@ class RDoc::Markup::AttributeManager
108
117
  }
109
118
  end
110
119
 
120
+ ##
121
+ # Converts special sequences to RDoc attributes
122
+
111
123
  def convert_specials(str, attrs)
112
124
  unless SPECIAL.empty?
113
125
  SPECIAL.each do |regexp, attr|
@@ -125,15 +137,25 @@ class RDoc::Markup::AttributeManager
125
137
 
126
138
  PROTECTABLE = %w[<\\]
127
139
 
140
+ ##
141
+ # Escapes special sequences of text to prevent conversion to RDoc
142
+
128
143
  def mask_protected_sequences
129
144
  protect_pattern = Regexp.new("\\\\([#{Regexp.escape(PROTECTABLE.join(''))}])")
130
145
  @str.gsub!(protect_pattern, "\\1#{PROTECT_ATTR}")
131
146
  end
132
147
 
148
+ ##
149
+ # Unescapes special sequences of text
150
+
133
151
  def unmask_protected_sequences
134
152
  @str.gsub!(/(.)#{PROTECT_ATTR}/, "\\1\000")
135
153
  end
136
154
 
155
+ ##
156
+ # Creates a new attribute manager that understands bold, emphasized and
157
+ # teletype text.
158
+
137
159
  def initialize
138
160
  add_word_pair("*", "*", :BOLD)
139
161
  add_word_pair("_", "_", :EM)
@@ -146,6 +168,12 @@ class RDoc::Markup::AttributeManager
146
168
  add_html("code", :TT)
147
169
  end
148
170
 
171
+ ##
172
+ # Adds a markup class with +name+ for words wrapped in the +start+ and
173
+ # +stop+ character. To make words wrapped with "*" bold:
174
+ #
175
+ # am.add_word_pair '*', '*', :BOLD
176
+
149
177
  def add_word_pair(start, stop, name)
150
178
  raise ArgumentError, "Word flags may not start with '<'" if
151
179
  start[0,1] == '<'
@@ -163,14 +191,29 @@ class RDoc::Markup::AttributeManager
163
191
  PROTECTABLE.uniq!
164
192
  end
165
193
 
194
+ ##
195
+ # Adds a markup class with +name+ for words surrounded by HTML tag +tag+.
196
+ # To process emphasis tags:
197
+ #
198
+ # am.add_html 'em', :EM
199
+
166
200
  def add_html(tag, name)
167
201
  HTML_TAGS[tag.downcase] = RDoc::Markup::Attribute.bitmap_for name
168
202
  end
169
203
 
204
+ ##
205
+ # Adds a special handler for +pattern+ with +name+. A simple URL handler
206
+ # would be:
207
+ #
208
+ # @am.add_special(/((https?:)\S+\w)/, :HYPERLINK)
209
+
170
210
  def add_special(pattern, name)
171
211
  SPECIAL[pattern] = RDoc::Markup::Attribute.bitmap_for name
172
212
  end
173
213
 
214
+ ##
215
+ # Processes +str+ converting attributes, HTML and specials
216
+
174
217
  def flow(str)
175
218
  @str = str
176
219
 
@@ -187,6 +230,9 @@ class RDoc::Markup::AttributeManager
187
230
  return split_into_flow
188
231
  end
189
232
 
233
+ ##
234
+ # Debug method that prints a string along with its attributes
235
+
190
236
  def display_attributes
191
237
  puts
192
238
  puts @str.tr(NULL, "!")
data/lib/rdoc/markup/formatter.rb CHANGED
@@ -1,11 +1,22 @@
1
1
  require 'rdoc/markup'
2
2
 
3
+ ##
4
+ # Base class for RDoc markup formatters
5
+ #
6
+ # Formatters use a visitor pattern to convert content into output.
7
+
3
8
  class RDoc::Markup::Formatter
4
9
 
10
+ ##
11
+ # Creates a new Formatter
12
+
5
13
  def initialize
6
14
  @markup = RDoc::Markup.new
7
15
  end
8
16
 
17
+ ##
18
+ # Marks up +content+
19
+
9
20
  def convert(content)
10
21
  @markup.convert content, self
11
22
  end
data/lib/rdoc/markup/fragments.rb CHANGED
@@ -54,16 +54,26 @@ class RDoc::Markup
54
54
  type_name :PARAGRAPH
55
55
  end
56
56
 
57
+ ##
58
+ # An empty line
59
+
57
60
  class BlankLine < Paragraph
58
61
  type_name :BLANK
59
62
  end
60
63
 
64
+ ##
65
+ # A heading
66
+
61
67
  class Heading < Paragraph
62
68
  type_name :HEADING
63
69
 
70
+ ##
71
+ # Level of heading, smaller is more important
72
+
64
73
  def head_level
65
74
  @param.to_i
66
75
  end
76
+
67
77
  end
68
78
 
69
79
  ##
@@ -80,10 +90,13 @@ class RDoc::Markup
80
90
  ]
81
91
  end
82
92
 
93
+ ##
94
+ # An item in a list
95
+
83
96
  class ListItem < ListBase
84
97
  type_name :LIST
85
98
 
86
- def to_s
99
+ def to_s # :nodoc:
87
100
  text = if [:NOTE, :LABELED].include? type then
88
101
  "#{@param}: #{@txt}"
89
102
  else
@@ -95,13 +108,27 @@ class RDoc::Markup
95
108
 
96
109
  end
97
110
 
111
+ ##
112
+ # Start of a list
113
+
98
114
  class ListStart < ListBase
115
+
116
+ ##
117
+ # Creates a ListStart with nesting +level+
118
+
99
119
  def initialize(level, param, type)
100
120
  super(level, param, type, nil)
101
121
  end
102
122
  end
103
123
 
124
+ ##
125
+ # End of a list
126
+
104
127
  class ListEnd < ListBase
128
+
129
+ ##
130
+ # Creates a ListEnd with nesting +level+
131
+
105
132
  def initialize(level, type)
106
133
  super(level, "", type, nil)
107
134
  end
@@ -113,6 +140,9 @@ class RDoc::Markup
113
140
  class Verbatim < Fragment
114
141
  type_name :VERBATIM
115
142
 
143
+ ##
144
+ # Adds +txt+ to this verbatim
145
+
116
146
  def add_text(txt)
117
147
  @txt << txt.chomp << "\n"
118
148
  end
@@ -132,14 +162,23 @@ class RDoc::Markup
132
162
 
133
163
  class LineCollection
134
164
 
165
+ ##
166
+ # Creates a new collection of lines
167
+
135
168
  def initialize
136
169
  @fragments = []
137
170
  end
138
171
 
172
+ ##
173
+ # Adds +fragment+ to the collection
174
+
139
175
  def add(fragment)
140
176
  @fragments << fragment
141
177
  end
142
178
 
179
+ ##
180
+ # Iterates over the lines in the collection
181
+
143
182
  def each(&b)
144
183
  @fragments.each(&b)
145
184
  end
@@ -165,7 +204,7 @@ class RDoc::Markup
165
204
  tidy_blank_lines
166
205
  end
167
206
 
168
- def to_s
207
+ def to_s # :nodoc:
169
208
  @fragments.join("\n----\n")
170
209
  end
171
210
 
@@ -198,6 +237,7 @@ class RDoc::Markup
198
237
 
199
238
  private
200
239
 
240
+ ##
201
241
  # If you have:
202
242
  #
203
243
  # normal paragraph text.
data/lib/rdoc/markup/inline.rb CHANGED
@@ -37,16 +37,17 @@ class RDoc::Markup
37
37
  yield name.to_s if (bitmap & bit) != 0
38
38
  end
39
39
  end
40
+
40
41
  end
41
42
 
42
- AttrChanger = Struct.new(:turn_on, :turn_off)
43
+ AttrChanger = Struct.new :turn_on, :turn_off
43
44
 
44
45
  ##
45
46
  # An AttrChanger records a change in attributes. It contains a bitmap of the
46
47
  # attributes to turn on, and a bitmap of those to turn off.
47
48
 
48
49
  class AttrChanger
49
- def to_s
50
+ def to_s # :nodoc:
50
51
  "Attr: +#{Attribute.as_string(turn_on)}/-#{Attribute.as_string(turn_on)}"
51
52
  end
52
53
  end
@@ -55,42 +56,66 @@ class RDoc::Markup
55
56
  # An array of attributes which parallels the characters in a string.
56
57
 
57
58
  class AttrSpan
59
+
60
+ ##
61
+ # Creates a new AttrSpan for +length+ characters
62
+
58
63
  def initialize(length)
59
64
  @attrs = Array.new(length, 0)
60
65
  end
61
66
 
67
+ ##
68
+ # Toggles +bits+ from +start+ to +length+
62
69
  def set_attrs(start, length, bits)
63
70
  for i in start ... (start+length)
64
71
  @attrs[i] |= bits
65
72
  end
66
73
  end
67
74
 
75
+ ##
76
+ # Acccesses flags for character +n+
77
+
68
78
  def [](n)
69
79
  @attrs[n]
70
80
  end
81
+
71
82
  end
72
83
 
73
84
  ##
74
85
  # Hold details of a special sequence
75
86
 
76
87
  class Special
88
+
89
+ ##
90
+ # Special type
91
+
77
92
  attr_reader :type
93
+
94
+ ##
95
+ # Special text
96
+
78
97
  attr_accessor :text
79
98
 
99
+ ##
100
+ # Creates a new special sequence of +type+ with +text+
101
+
80
102
  def initialize(type, text)
81
103
  @type, @text = type, text
82
104
  end
83
105
 
106
+ ##
107
+ # Specials are equal when the have the same text and type
108
+
84
109
  def ==(o)
85
110
  self.text == o.text && self.type == o.type
86
111
  end
87
112
 
88
- def inspect
113
+ def inspect # :nodoc:
89
114
  "#<RDoc::Markup::Special:0x%x @type=%p, name=%p @text=%p>" % [
90
115
  object_id, @type, RDoc::Markup::Attribute.as_string(type), text.dump]
91
116
  end
92
117
 
93
- def to_s
118
+ def to_s # :nodoc:
94
119
  "Special: type=#{type}, name=#{RDoc::Markup::Attribute.as_string type}, text=#{text.dump}"
95
120
  end
96
121