rdoc 2.4.1 → 2.4.2
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.
- data.tar.gz.sig +0 -0
- data/History.txt +25 -0
- data/Manifest.txt +2 -0
- data/Rakefile +1 -0
- data/lib/rdoc.rb +17 -24
- data/lib/rdoc/context.rb +1 -1
- data/lib/rdoc/generator/darkfish.rb +1 -1
- data/lib/rdoc/generator/template/darkfish/classpage.rhtml +1 -1
- data/lib/rdoc/markup/attribute_manager.rb +2 -2
- data/lib/rdoc/markup/to_html_crossref.rb +3 -1
- data/lib/rdoc/options.rb +126 -104
- data/lib/rdoc/parser/c.rb +1 -0
- data/lib/rdoc/parser/ruby.rb +62 -55
- data/lib/rdoc/rdoc.rb +253 -239
- data/lib/rdoc/ri/driver.rb +5 -5
- data/lib/rdoc/task.rb +276 -0
- data/lib/rdoc/top_level.rb +10 -0
- data/test/test_rdoc_markup_attribute_manager.rb +9 -0
- data/test/test_rdoc_markup_to_html.rb +1 -0
- data/test/test_rdoc_markup_to_html_crossref.rb +1 -0
- data/test/test_rdoc_parser_c.rb +28 -0
- data/test/test_rdoc_parser_ruby.rb +90 -2
- data/test/test_rdoc_task.rb +64 -0
- metadata +21 -7
- metadata.gz.sig +0 -0
data/lib/rdoc/ri/driver.rb
CHANGED
@@ -550,8 +550,8 @@ Options may also be set in the 'RI' environment variable.
|
|
550
550
|
|
551
551
|
cache = load_cache_for klass
|
552
552
|
|
553
|
-
methods += cache.keys.select do |
|
554
|
-
|
553
|
+
methods += cache.keys.select do |method_name|
|
554
|
+
method_name =~ /^#{klass}#{method_type}#{method}/
|
555
555
|
end
|
556
556
|
|
557
557
|
# TODO ancestor lookup
|
@@ -609,7 +609,7 @@ Options may also be set in the 'RI' environment variable.
|
|
609
609
|
expanded << '::' unless expanded.empty?
|
610
610
|
short = expanded << klass_part
|
611
611
|
|
612
|
-
subset = class_cache.keys.select do |
|
612
|
+
subset = class_cache.keys.select do |klass_name|
|
613
613
|
klass =~ /^#{expanded}[^:]*$/
|
614
614
|
end
|
615
615
|
|
@@ -673,8 +673,8 @@ Options may also be set in the 'RI' environment variable.
|
|
673
673
|
if system_file then
|
674
674
|
method["source_path"] = "Ruby #{RDoc::RI::Paths::VERSION}"
|
675
675
|
else
|
676
|
-
gem = Gem.path.any? do |
|
677
|
-
pattern = File.join Regexp.escape(
|
676
|
+
gem = Gem.path.any? do |gem_path|
|
677
|
+
pattern = File.join Regexp.escape(gem_path), 'doc', '(.*?)', ''
|
678
678
|
|
679
679
|
f =~ /^#{pattern}/
|
680
680
|
end
|
data/lib/rdoc/task.rb
ADDED
@@ -0,0 +1,276 @@
|
|
1
|
+
# Copyright (c) 2003, 2004 Jim Weirich, 2009 Eric Hodel
|
2
|
+
#
|
3
|
+
# Permission is hereby granted, free of charge, to any person obtaining
|
4
|
+
# a copy of this software and associated documentation files (the
|
5
|
+
# "Software"), to deal in the Software without restriction, including
|
6
|
+
# without limitation the rights to use, copy, modify, merge, publish,
|
7
|
+
# distribute, sublicense, and/or sell copies of the Software, and to
|
8
|
+
# permit persons to whom the Software is furnished to do so, subject to
|
9
|
+
# the following conditions:
|
10
|
+
#
|
11
|
+
# The above copyright notice and this permission notice shall be
|
12
|
+
# included in all copies or substantial portions of the Software.
|
13
|
+
#
|
14
|
+
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
15
|
+
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
16
|
+
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
17
|
+
# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
18
|
+
# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
19
|
+
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
20
|
+
# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
21
|
+
|
22
|
+
require 'rubygems'
|
23
|
+
begin
|
24
|
+
gem 'rdoc'
|
25
|
+
rescue Gem::LoadError
|
26
|
+
end
|
27
|
+
|
28
|
+
begin
|
29
|
+
gem 'rake'
|
30
|
+
rescue Gem::LoadError
|
31
|
+
end
|
32
|
+
|
33
|
+
require 'rdoc'
|
34
|
+
require 'rake'
|
35
|
+
require 'rake/tasklib'
|
36
|
+
|
37
|
+
##
|
38
|
+
# Create a documentation task that will generate the RDoc files for a project.
|
39
|
+
#
|
40
|
+
# The RDoc::Task will create the following targets:
|
41
|
+
#
|
42
|
+
# [<b><em>rdoc</em></b>]
|
43
|
+
# Main task for this RDoc task.
|
44
|
+
#
|
45
|
+
# [<b>:clobber_<em>rdoc</em></b>]
|
46
|
+
# Delete all the rdoc files. This target is automatically added to the main
|
47
|
+
# clobber target.
|
48
|
+
#
|
49
|
+
# [<b>:re<em>rdoc</em></b>]
|
50
|
+
# Rebuild the rdoc files from scratch, even if they are not out of date.
|
51
|
+
#
|
52
|
+
# Simple Example:
|
53
|
+
#
|
54
|
+
# RDoc::Task.new do |rd|
|
55
|
+
# rd.main = "README.rdoc"
|
56
|
+
# rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
|
57
|
+
# end
|
58
|
+
#
|
59
|
+
# The +rd+ object passed to the block is an RDoc::Task object. See the
|
60
|
+
# attributes list for the RDoc::Task class for available customization options.
|
61
|
+
#
|
62
|
+
# == Specifying different task names
|
63
|
+
#
|
64
|
+
# You may wish to give the task a different name, such as if you are
|
65
|
+
# generating two sets of documentation. For instance, if you want to have a
|
66
|
+
# development set of documentation including private methods:
|
67
|
+
#
|
68
|
+
# RDoc::Task.new :rdoc_dev do |rd|
|
69
|
+
# rd.main = "README.doc"
|
70
|
+
# rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
|
71
|
+
# rd.options << "--all"
|
72
|
+
# end
|
73
|
+
#
|
74
|
+
# The tasks would then be named :<em>rdoc_dev</em>,
|
75
|
+
# :clobber_<em>rdoc_dev</em>, and :re<em>rdoc_dev</em>.
|
76
|
+
#
|
77
|
+
# If you wish to have completely different task names, then pass a Hash as
|
78
|
+
# first argument. With the <tt>:rdoc</tt>, <tt>:clobber_rdoc</tt> and
|
79
|
+
# <tt>:rerdoc</tt> options, you can customize the task names to your liking.
|
80
|
+
#
|
81
|
+
# For example:
|
82
|
+
#
|
83
|
+
# RDoc::Task.new(:rdoc => "rdoc", :clobber_rdoc => "rdoc:clean",
|
84
|
+
# :rerdoc => "rdoc:force")
|
85
|
+
#
|
86
|
+
# This will create the tasks <tt>:rdoc</tt>, <tt>:rdoc_clean</tt> and
|
87
|
+
# <tt>:rdoc:force</tt>.
|
88
|
+
|
89
|
+
class RDoc::Task < Rake::TaskLib
|
90
|
+
|
91
|
+
##
|
92
|
+
# Name of the main, top level task. (default is :rdoc)
|
93
|
+
|
94
|
+
attr_accessor :name
|
95
|
+
|
96
|
+
##
|
97
|
+
# Name of directory to receive the html output files. (default is "html")
|
98
|
+
|
99
|
+
attr_accessor :rdoc_dir
|
100
|
+
|
101
|
+
##
|
102
|
+
# Title of RDoc documentation. (defaults to rdoc's default)
|
103
|
+
|
104
|
+
attr_accessor :title
|
105
|
+
|
106
|
+
##
|
107
|
+
# Name of file to be used as the main, top level file of the RDoc. (default
|
108
|
+
# is none)
|
109
|
+
|
110
|
+
attr_accessor :main
|
111
|
+
|
112
|
+
##
|
113
|
+
# Name of template to be used by rdoc. (defaults to rdoc's default)
|
114
|
+
|
115
|
+
attr_accessor :template
|
116
|
+
|
117
|
+
##
|
118
|
+
# List of files to be included in the rdoc generation. (default is [])
|
119
|
+
|
120
|
+
attr_accessor :rdoc_files
|
121
|
+
|
122
|
+
##
|
123
|
+
# Additional list of options to be passed rdoc. (default is [])
|
124
|
+
|
125
|
+
attr_accessor :options
|
126
|
+
|
127
|
+
##
|
128
|
+
# Whether to run the rdoc process as an external shell (default is false)
|
129
|
+
|
130
|
+
attr_accessor :external
|
131
|
+
|
132
|
+
##
|
133
|
+
# Create an RDoc task with the given name. See the RDoc::Task class overview
|
134
|
+
# for documentation.
|
135
|
+
|
136
|
+
def initialize(name = :rdoc) # :yield: self
|
137
|
+
if name.is_a? Hash then
|
138
|
+
invalid_options = name.keys.map { |k| k.to_sym } -
|
139
|
+
[:rdoc, :clobber_rdoc, :rerdoc]
|
140
|
+
|
141
|
+
unless invalid_options.empty? then
|
142
|
+
raise ArgumentError, "invalid options: #{invalid_options.join(", ")}"
|
143
|
+
end
|
144
|
+
end
|
145
|
+
|
146
|
+
@name = name
|
147
|
+
@rdoc_files = Rake::FileList.new
|
148
|
+
@rdoc_dir = 'html'
|
149
|
+
@main = nil
|
150
|
+
@title = nil
|
151
|
+
@template = nil
|
152
|
+
@external = false
|
153
|
+
@options = []
|
154
|
+
yield self if block_given?
|
155
|
+
define
|
156
|
+
end
|
157
|
+
|
158
|
+
##
|
159
|
+
# Create the tasks defined by this task lib.
|
160
|
+
|
161
|
+
def define
|
162
|
+
if rdoc_task_name != "rdoc" then
|
163
|
+
desc "Build the RDoc HTML Files"
|
164
|
+
else
|
165
|
+
desc "Build the #{rdoc_task_name} HTML Files"
|
166
|
+
end
|
167
|
+
task rdoc_task_name
|
168
|
+
|
169
|
+
desc "Force a rebuild of the RDoc files"
|
170
|
+
task rerdoc_task_name => [clobber_task_name, rdoc_task_name]
|
171
|
+
|
172
|
+
desc "Remove RDoc products"
|
173
|
+
task clobber_task_name do
|
174
|
+
rm_r rdoc_dir rescue nil
|
175
|
+
end
|
176
|
+
|
177
|
+
task :clobber => [clobber_task_name]
|
178
|
+
|
179
|
+
directory @rdoc_dir
|
180
|
+
task rdoc_task_name => [rdoc_target]
|
181
|
+
file rdoc_target => @rdoc_files + [Rake.application.rakefile] do
|
182
|
+
rm_r @rdoc_dir rescue nil
|
183
|
+
@before_running_rdoc.call if @before_running_rdoc
|
184
|
+
args = option_list + @rdoc_files
|
185
|
+
|
186
|
+
if @external then
|
187
|
+
argstring = args.join(' ')
|
188
|
+
sh %{ruby -Ivendor vendor/rd #{argstring}}
|
189
|
+
else
|
190
|
+
if Rake.application.options.trace then
|
191
|
+
$stderr.puts "rdoc #{args.join ' '}"
|
192
|
+
end
|
193
|
+
require 'rdoc/rdoc'
|
194
|
+
RDoc::RDoc.new.document(args)
|
195
|
+
end
|
196
|
+
end
|
197
|
+
|
198
|
+
self
|
199
|
+
end
|
200
|
+
|
201
|
+
def option_list
|
202
|
+
result = @options.dup
|
203
|
+
result << "-o" << @rdoc_dir
|
204
|
+
result << "--main" << quote(main) if main
|
205
|
+
result << "--title" << quote(title) if title
|
206
|
+
result << "-T" << quote(template) if template
|
207
|
+
result
|
208
|
+
end
|
209
|
+
|
210
|
+
def quote(str)
|
211
|
+
if @external
|
212
|
+
"'#{str}'"
|
213
|
+
else
|
214
|
+
str
|
215
|
+
end
|
216
|
+
end
|
217
|
+
|
218
|
+
def option_string
|
219
|
+
option_list.join(' ')
|
220
|
+
end
|
221
|
+
|
222
|
+
##
|
223
|
+
# The block passed to this method will be called just before running the
|
224
|
+
# RDoc generator. It is allowed to modify RDoc::Task attributes inside the
|
225
|
+
# block.
|
226
|
+
|
227
|
+
def before_running_rdoc(&block)
|
228
|
+
@before_running_rdoc = block
|
229
|
+
end
|
230
|
+
|
231
|
+
private
|
232
|
+
|
233
|
+
def rdoc_target
|
234
|
+
"#{rdoc_dir}/index.html"
|
235
|
+
end
|
236
|
+
|
237
|
+
def rdoc_task_name
|
238
|
+
case name
|
239
|
+
when Hash
|
240
|
+
(name[:rdoc] || "rdoc").to_s
|
241
|
+
else
|
242
|
+
name.to_s
|
243
|
+
end
|
244
|
+
end
|
245
|
+
|
246
|
+
def clobber_task_name
|
247
|
+
case name
|
248
|
+
when Hash
|
249
|
+
(name[:clobber_rdoc] || "clobber_rdoc").to_s
|
250
|
+
else
|
251
|
+
"clobber_#{name}"
|
252
|
+
end
|
253
|
+
end
|
254
|
+
|
255
|
+
def rerdoc_task_name
|
256
|
+
case name
|
257
|
+
when Hash
|
258
|
+
(name[:rerdoc] || "rerdoc").to_s
|
259
|
+
else
|
260
|
+
"re#{name}"
|
261
|
+
end
|
262
|
+
end
|
263
|
+
|
264
|
+
end
|
265
|
+
|
266
|
+
# :stopdoc:
|
267
|
+
module Rake
|
268
|
+
|
269
|
+
##
|
270
|
+
# For backwards compatibility
|
271
|
+
|
272
|
+
RDocTask = RDoc::Task
|
273
|
+
|
274
|
+
end
|
275
|
+
# :startdoc:
|
276
|
+
|
data/lib/rdoc/top_level.rb
CHANGED
@@ -147,6 +147,16 @@ class RDoc::TopLevel < RDoc::Context
|
|
147
147
|
end
|
148
148
|
end
|
149
149
|
|
150
|
+
##
|
151
|
+
# Adds +method+ to Object instead of RDoc::TopLevel
|
152
|
+
|
153
|
+
def add_method(method)
|
154
|
+
object = self.class.find_class_named 'Object'
|
155
|
+
object = add_class RDoc::NormalClass, 'Object' unless object
|
156
|
+
|
157
|
+
object.add_method method
|
158
|
+
end
|
159
|
+
|
150
160
|
##
|
151
161
|
# Base name of this file
|
152
162
|
|
@@ -124,6 +124,10 @@ class TestRDocMarkupAttributeManager < MiniTest::Unit::TestCase
|
|
124
124
|
@am.flow("*\\bold*")
|
125
125
|
end
|
126
126
|
|
127
|
+
def test_bold_html_escaped
|
128
|
+
assert_equal ['cat <b>dog</b>'], @am.flow('cat \<b>dog</b>')
|
129
|
+
end
|
130
|
+
|
127
131
|
def test_combined
|
128
132
|
assert_equal(["cat ", @em_on, "and", @em_off, " ", @bold_on, "dog", @bold_off],
|
129
133
|
@am.flow("cat _and_ *dog*"))
|
@@ -229,6 +233,11 @@ class TestRDocMarkupAttributeManager < MiniTest::Unit::TestCase
|
|
229
233
|
assert_equal(["cats' ", crossref("#fred")].flatten, @am.flow("cats' #fred"))
|
230
234
|
end
|
231
235
|
|
236
|
+
def test_tt_html
|
237
|
+
assert_equal [@tt_on, '"\n"', @tt_off],
|
238
|
+
@am.flow('<tt>"\n"</tt>')
|
239
|
+
end
|
240
|
+
|
232
241
|
end
|
233
242
|
|
234
243
|
MiniTest::Unit.autorun
|
@@ -48,6 +48,7 @@ class TestRDocMarkupToHtml < MiniTest::Unit::TestCase
|
|
48
48
|
def test_tt_formatting
|
49
49
|
assert_equal "<p>\n<tt>--</tt> — <tt>cats'</tt> cats’\n</p>\n",
|
50
50
|
util_format("<tt>--</tt> -- <tt>cats'</tt> cats'")
|
51
|
+
|
51
52
|
assert_equal "<p>\n<b>—</b>\n</p>\n", util_format("<b>--</b>")
|
52
53
|
end
|
53
54
|
|
data/test/test_rdoc_parser_c.rb
CHANGED
@@ -358,6 +358,34 @@ Init_IO(void) {
|
|
358
358
|
assert_equal " Method Comment! \n", read_method.comment
|
359
359
|
end
|
360
360
|
|
361
|
+
def test_define_method_private
|
362
|
+
content = <<-EOF
|
363
|
+
/*Method Comment! */
|
364
|
+
static VALUE
|
365
|
+
rb_io_s_read(argc, argv, io)
|
366
|
+
int argc;
|
367
|
+
VALUE *argv;
|
368
|
+
VALUE io;
|
369
|
+
{
|
370
|
+
}
|
371
|
+
|
372
|
+
void
|
373
|
+
Init_IO(void) {
|
374
|
+
/*
|
375
|
+
* a comment for class Foo on rb_define_class
|
376
|
+
*/
|
377
|
+
VALUE rb_cIO = rb_define_class("IO", rb_cObject);
|
378
|
+
rb_define_private_method(rb_cIO, "read", rb_io_s_read, -1);
|
379
|
+
}
|
380
|
+
EOF
|
381
|
+
|
382
|
+
klass = util_get_class content, 'rb_cIO'
|
383
|
+
read_method = klass.method_list.first
|
384
|
+
assert_equal 'IO#read', read_method.full_name
|
385
|
+
assert_equal :private, read_method.visibility
|
386
|
+
assert_equal " Method Comment! \n", read_method.comment
|
387
|
+
end
|
388
|
+
|
361
389
|
def util_get_class(content, name)
|
362
390
|
@parser = util_parser content
|
363
391
|
@parser.scan
|
@@ -1,7 +1,7 @@
|
|
1
1
|
require 'stringio'
|
2
2
|
require 'tempfile'
|
3
3
|
require 'rubygems'
|
4
|
-
require 'minitest/
|
4
|
+
require 'minitest/autorun'
|
5
5
|
|
6
6
|
require 'rdoc/options'
|
7
7
|
require 'rdoc/parser/ruby'
|
@@ -697,6 +697,95 @@ EOF
|
|
697
697
|
assert klass.method_list.empty?
|
698
698
|
end
|
699
699
|
|
700
|
+
def test_parse_method_no_parens
|
701
|
+
klass = RDoc::NormalClass.new 'Foo'
|
702
|
+
klass.parent = @top_level
|
703
|
+
|
704
|
+
comment = "##\n# my method\n"
|
705
|
+
|
706
|
+
util_parser "def foo arg1, arg2\nend"
|
707
|
+
|
708
|
+
tk = @parser.get_tk
|
709
|
+
|
710
|
+
@parser.parse_method klass, RDoc::Parser::Ruby::NORMAL, tk, comment
|
711
|
+
|
712
|
+
foo = klass.method_list.first
|
713
|
+
assert_equal '(arg1, arg2)', foo.params
|
714
|
+
end
|
715
|
+
|
716
|
+
def test_parse_method_parameters_comment
|
717
|
+
klass = RDoc::NormalClass.new 'Foo'
|
718
|
+
klass.parent = @top_level
|
719
|
+
|
720
|
+
comment = "##\n# my method\n"
|
721
|
+
|
722
|
+
util_parser "def foo arg1, arg2 # some useful comment\nend"
|
723
|
+
|
724
|
+
tk = @parser.get_tk
|
725
|
+
|
726
|
+
@parser.parse_method klass, RDoc::Parser::Ruby::NORMAL, tk, comment
|
727
|
+
|
728
|
+
foo = klass.method_list.first
|
729
|
+
assert_equal '(arg1, arg2)', foo.params
|
730
|
+
end
|
731
|
+
|
732
|
+
def test_parse_method_parameters_comment_continue
|
733
|
+
klass = RDoc::NormalClass.new 'Foo'
|
734
|
+
klass.parent = @top_level
|
735
|
+
|
736
|
+
comment = "##\n# my method\n"
|
737
|
+
|
738
|
+
util_parser "def foo arg1, arg2, # some useful comment\narg3\nend"
|
739
|
+
|
740
|
+
tk = @parser.get_tk
|
741
|
+
|
742
|
+
@parser.parse_method klass, RDoc::Parser::Ruby::NORMAL, tk, comment
|
743
|
+
|
744
|
+
foo = klass.method_list.first
|
745
|
+
assert_equal '(arg1, arg2, arg3)', foo.params
|
746
|
+
end
|
747
|
+
|
748
|
+
def test_parse_method_toplevel
|
749
|
+
klass = @top_level
|
750
|
+
|
751
|
+
comment = "##\n# my method\n"
|
752
|
+
|
753
|
+
util_parser "def foo arg1, arg2\nend"
|
754
|
+
|
755
|
+
tk = @parser.get_tk
|
756
|
+
|
757
|
+
@parser.parse_method klass, RDoc::Parser::Ruby::NORMAL, tk, comment
|
758
|
+
|
759
|
+
object = RDoc::TopLevel.find_class_named 'Object'
|
760
|
+
|
761
|
+
foo = object.method_list.first
|
762
|
+
assert_equal 'Object#foo', foo.full_name
|
763
|
+
end
|
764
|
+
|
765
|
+
def test_parse_statements_class_if
|
766
|
+
comment = "##\n# my method\n"
|
767
|
+
|
768
|
+
util_parser <<-CODE
|
769
|
+
module Foo
|
770
|
+
X = if TRUE then
|
771
|
+
''
|
772
|
+
end
|
773
|
+
|
774
|
+
def blah
|
775
|
+
end
|
776
|
+
end
|
777
|
+
CODE
|
778
|
+
|
779
|
+
@parser.parse_statements @top_level, RDoc::Parser::Ruby::NORMAL, nil, ''
|
780
|
+
|
781
|
+
foo = @top_level.modules.first
|
782
|
+
assert_equal 'Foo', foo.full_name, 'module Foo'
|
783
|
+
|
784
|
+
methods = foo.method_list
|
785
|
+
assert_equal 1, methods.length
|
786
|
+
assert_equal 'Foo#blah', methods.first.full_name
|
787
|
+
end
|
788
|
+
|
700
789
|
def test_parse_statements_class_nested
|
701
790
|
comment = "##\n# my method\n"
|
702
791
|
|
@@ -949,4 +1038,3 @@ EOF
|
|
949
1038
|
|
950
1039
|
end
|
951
1040
|
|
952
|
-
MiniTest::Unit.autorun
|