rdoc 3.5.3 → 3.6

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 CHANGED
Binary file
@@ -1,3 +1,28 @@
1
+ === 3.6 / 2011-05-13
2
+
3
+ * Major Enhancements
4
+ * Interactive ri is now the default when no names are given.
5
+ * Minor Enhancements
6
+ * RDoc::RDoc#generate was added to allow multiple generators to be used with
7
+ a set of parsed file info.
8
+ * RDoc::Options#finish can be called multiple times now.
9
+ * `ri -i` only shows one level of namespace when completing class names.
10
+ * Added `ri --list` for explicit listing. `ri -l F G` will list all classes
11
+ or modules starting with F or G
12
+ * Bug fixes
13
+ * Remove windows-specific test for test_check_files, it is too hard to do.
14
+ Ruby commit r30811 by Usaku Nakamura.
15
+ * Remove unnecessary (and wrong) platform-dependent hacks. Ruby commit
16
+ r30829 by Usaku Nakamura.
17
+ * Completing via Array#[ in `ri -i` no longer crashes. Ruby Bug #3167
18
+ * Completing IO::o in `ri -i` now returns results. Ruby Bug #3167
19
+ * RDoc::Parser::C ignores prototypes better. Pull Request #34 by Pete
20
+ Higgins.
21
+ * private_class_method and public_class_method are now parsed correctly for
22
+ inherited methods. Issue #16 by gitsucks.
23
+ * The doc directive now forces documentation even when the method is marked
24
+ private or protected.
25
+
1
26
  === 3.5.3 / 2010-02-06
2
27
 
3
28
  * Bug fixes
data/README.txt CHANGED
@@ -14,15 +14,31 @@ See RDoc for a description of RDoc's markup and basic use.
14
14
 
15
15
  == SYNOPSIS:
16
16
 
17
- To generate HTML documentation:
17
+ To learn RDoc's syntax and directives for documenting your ruby project see
18
+ RDoc::Markup. RDoc::Parser::Ruby and RDoc::Parser::C have additional
19
+ directives (such as metaprogrammed methods) for documenting Ruby and C files
20
+ respectively.
18
21
 
19
- rdoc .
22
+ To generate HTML documentation for your project run <tt>rdoc .</tt> in your
23
+ project's root directory.
24
+
25
+ To determine how well your project is documented run <tt>rdoc -C lib</tt> to
26
+ get a documentation coverage report. <tt>rdoc -C1 lib</tt> includes parameter
27
+ names in the documentation coverage report.
28
+
29
+ To generate documentation using +rake+ see RDoc::Task.
20
30
 
21
31
  To generate documentation programmatically:
22
32
 
23
33
  gem 'rdoc'
24
34
  require 'rdoc/rdoc'
25
- # ... see RDoc
35
+
36
+ options = RDoc::Options.new
37
+ # see RDoc::Options
38
+
39
+ rdoc = RDoc::RDoc.new
40
+ rdoc.document options
41
+ # see RDoc::RDoc
26
42
 
27
43
  == BUGS:
28
44
 
data/Rakefile CHANGED
@@ -29,31 +29,7 @@ Hoe.spec 'rdoc' do
29
29
 
30
30
  extra_rdoc_files << 'Rakefile'
31
31
  spec_extras['required_rubygems_version'] = '>= 1.3'
32
- spec_extras['homepage'] = 'http://rdoc.rubyforge.org'
33
-
34
- spec_extras[:post_install_message] = <<-EOF
35
- NOTE: If you are running Ruby 1.9.2 you can ignore this message.
36
-
37
- RDoc 2.5+ has a new ri data format for Ruby 1.8.7 and 1.9.1. (1.9.2 contains
38
- RDoc 2.5 so there is nothing to do!)
39
-
40
- To install new ri data for core and stdlib you'll need to:
41
-
42
- gem install rdoc-data
43
-
44
- then run:
45
-
46
- rdoc-data --install
47
-
48
- To have ri data for you gems you'll also need to run:
49
-
50
- gem rdoc --all --overwrite
51
-
52
- If you don't want to rebuild the rdoc for `gem server`, add --no-rdoc.
53
-
54
- NOTE: RDoc 2.5 did not save method parameters, so you should upgrade your
55
- rdoc-data gem to a version >= 2.5.3 if you installed an older version.
56
- EOF
32
+ spec_extras['homepage'] = 'http://docs.seattlerb.org/rdoc'
57
33
  end
58
34
 
59
35
  # These tasks expect to have the following directory structure:
@@ -3,31 +3,39 @@ $DEBUG_RDOC = nil
3
3
  # :main: README.txt
4
4
 
5
5
  ##
6
- # = \RDoc - Ruby Documentation System
7
- #
8
- # This package contains RDoc and RDoc::Markup. RDoc is an application that
9
- # produces documentation for one or more Ruby source files. It works similarly
10
- # to JavaDoc, parsing the source, and extracting the definition for classes,
11
- # modules, and methods (along with includes and requires). It associates with
12
- # these optional documentation contained in the immediately preceding comment
13
- # block, and then renders the result using a pluggable output formatter.
14
- # RDoc::Markup is a library that converts plain text into various output
15
- # formats. The markup library is used to interpret the comment blocks that
16
- # RDoc uses to document methods, classes, and so on.
6
+ # RDoc is a Ruby documentation system which contains RDoc::RDoc for generating
7
+ # documentation, RDoc::RI for interactive documentation and RDoc::Markup for
8
+ # text markup.
9
+ #
10
+ # RDoc::RDoc produces documentation for Ruby source files. It works similarly
11
+ # to JavaDoc, parsing the source and extracting the definition for classes,
12
+ # modules, methods, includes and requires. It associates these with optional
13
+ # documentation contained in an immediately preceding comment block then
14
+ # renders the result using an output formatter.
15
+ #
16
+ # RDoc::Markup that converts plain text into various output formats. The
17
+ # markup library is used to interpret the comment blocks that RDoc uses to
18
+ # document methods, classes, and so on.
19
+ #
20
+ # RDoc::RI implements the +ri+ command-line tool which displays on-line
21
+ # documentation for ruby classes, methods, etc. +ri+ features several output
22
+ # formats and an interactive mode (<tt>ri -i</tt>). See <tt>ri --help</tt>
23
+ # for further details.
17
24
  #
18
25
  # == Roadmap
19
26
  #
20
27
  # * If you want to use RDoc to create documentation for your Ruby source files,
21
- # read the summary below, and refer to <tt>rdoc --help</tt> for command line
22
- # usage, and RDoc::Markup for a detailed description of RDoc's markup.
28
+ # see RDoc::Markup and refer to <tt>rdoc --help</tt> for command line
29
+ # usage.
23
30
  # * If you want to generate documentation for extensions written in C, see
24
31
  # RDoc::Parser::C
32
+ # * If you want to generate documentation using <tt>rake</tt> see RDoc::Task.
25
33
  # * If you want to drive RDoc programmatically, see RDoc::RDoc.
26
34
  # * If you want to use the library to format text blocks into HTML, look at
27
35
  # RDoc::Markup.
28
36
  # * If you want to make an RDoc plugin such as a generator or directive
29
37
  # handler see RDoc::RDoc.
30
- # * If you want to try writing your own output generator see RDoc::Generator.
38
+ # * If you want to write your own output generator see RDoc::Generator.
31
39
  #
32
40
  # == Summary
33
41
  #
@@ -95,7 +103,7 @@ module RDoc
95
103
  ##
96
104
  # RDoc version you are using
97
105
 
98
- VERSION = '3.5.3'
106
+ VERSION = '3.6'
99
107
 
100
108
  ##
101
109
  # Method visibilities
@@ -68,6 +68,19 @@ class RDoc::Attr < RDoc::MethodAttr
68
68
  end
69
69
  end
70
70
 
71
+ def inspect # :nodoc:
72
+ alias_for = @is_alias_for ? " (alias for #{@is_alias_for.name})" : nil
73
+ visibility = self.visibility
74
+ visibility = "forced #{visibility}" if force_documentation
75
+ "#<%s:0x%x %s %s (%s)%s>" % [
76
+ self.class, object_id,
77
+ full_name,
78
+ rw,
79
+ visibility,
80
+ alias_for,
81
+ ]
82
+ end
83
+
71
84
  ##
72
85
  # Dumps this Attr for use by ri. See also #marshal_load
73
86
 
@@ -137,12 +137,22 @@ class RDoc::ClassModule < RDoc::Context
137
137
  remove_invisible min_visibility
138
138
  end
139
139
 
140
+ ##
141
+ # Iterates the ancestors of this class or module for which an
142
+ # RDoc::ClassModule exists.
143
+
144
+ def each_ancestor # :yields: module
145
+ ancestors.each do |mod|
146
+ next if String === mod
147
+ yield mod
148
+ end
149
+ end
150
+
140
151
  ##
141
152
  # Looks for a symbol in the #ancestors. See Context#find_local_symbol.
142
153
 
143
154
  def find_ancestor_local_symbol symbol
144
- ancestors.each do |m|
145
- next if m.is_a?(String)
155
+ each_ancestor do |m|
146
156
  res = m.find_local_symbol(symbol)
147
157
  return res if res
148
158
  end
@@ -263,7 +273,7 @@ class RDoc::ClassModule < RDoc::Context
263
273
 
264
274
  class_module.each_attribute do |attr|
265
275
  if match = attributes.find { |a| a.name == attr.name } then
266
- match.rw = [match.rw, attr.rw].compact.join
276
+ match.rw = [match.rw, attr.rw].compact.uniq.join
267
277
  else
268
278
  add_attribute attr
269
279
  end
@@ -180,6 +180,20 @@ class RDoc::CodeObject
180
180
  @document_children = @document_self
181
181
  end
182
182
 
183
+ ##
184
+ # Yields each parent of this CodeObject. See also
185
+ # RDoc::ClassModule#each_ancestor
186
+
187
+ def each_parent
188
+ code_object = self
189
+
190
+ while code_object = code_object.parent do
191
+ yield code_object
192
+ end
193
+
194
+ self
195
+ end
196
+
183
197
  ##
184
198
  # Force the documentation of this object unless documentation
185
199
  # has been turned off by :endoc:
@@ -480,7 +480,7 @@ class RDoc::Context < RDoc::CodeObject
480
480
  # Adds included module +include+ which should be an RDoc::Include
481
481
 
482
482
  def add_include(include)
483
- add_to @includes, include
483
+ add_to @includes, include unless @includes.map { |i| i.full_name }.include?( include.full_name )
484
484
  end
485
485
 
486
486
  ##
@@ -950,10 +950,14 @@ class RDoc::Context < RDoc::CodeObject
950
950
  ##
951
951
  # Yields AnyMethod and Attr entries matching the list of names in +methods+.
952
952
 
953
- def methods_matching(methods, singleton = false)
953
+ def methods_matching(methods, singleton = false, &block)
954
954
  (@method_list + @attributes).each do |m|
955
955
  yield m if methods.include?(m.name) and m.singleton == singleton
956
956
  end
957
+
958
+ each_ancestor do |parent|
959
+ parent.methods_matching(methods, singleton, &block)
960
+ end
957
961
  end
958
962
 
959
963
  ##
@@ -1021,11 +1025,19 @@ class RDoc::Context < RDoc::CodeObject
1021
1025
  remove_invisible_in @attributes, min_visibility
1022
1026
  end
1023
1027
 
1028
+ ##
1029
+ # Only called when min_visibility == :public or :private
1030
+
1024
1031
  def remove_invisible_in(array, min_visibility) # :nodoc:
1025
1032
  if min_visibility == :public
1026
- array.reject! { |e| e.visibility != :public }
1033
+ array.reject! { |e|
1034
+ e.visibility != :public and not e.force_documentation
1035
+ }
1027
1036
  else
1028
- array.reject! { |e| e.visibility == :private }
1037
+ array.reject! { |e|
1038
+ e.visibility == :private and
1039
+ not e.force_documentation
1040
+ }
1029
1041
  end
1030
1042
  end
1031
1043
 
@@ -333,6 +333,8 @@ class RDoc::MethodAttr < RDoc::CodeObject
333
333
 
334
334
  def inspect # :nodoc:
335
335
  alias_for = @is_alias_for ? " (alias for #{@is_alias_for.name})" : nil
336
+ visibility = self.visibility
337
+ visibility = "forced #{visibility}" if force_documentation
336
338
  "#<%s:0x%x %s (%s)%s>" % [
337
339
  self.class, object_id,
338
340
  full_name,
@@ -256,7 +256,9 @@ class RDoc::Options
256
256
 
257
257
  @rdoc_include << "." if @rdoc_include.empty?
258
258
 
259
- if @exclude.empty? then
259
+ if @exclude.nil? or Regexp === @exclude then
260
+ # done, #finish is being re-run
261
+ elsif @exclude.empty? then
260
262
  @exclude = nil
261
263
  else
262
264
  @exclude = Regexp.new(@exclude.join("|"))
@@ -376,7 +376,7 @@ class RDoc::Parser::C < RDoc::Parser
376
376
  when %r%((?>/\*.*?\*/\s*)?)
377
377
  ((?:(?:static|SWIGINTERN)\s+)?
378
378
  (?:intern\s+)?VALUE\s+#{meth_name}
379
- \s*(\(.*?\))([^;]|$))%xm then
379
+ \s*(\([^)]*\))([^;]|$))%xm then
380
380
  comment = $1
381
381
  body = $2
382
382
  offset = $~.offset(2).first
@@ -1558,32 +1558,45 @@ class RDoc::Parser::Ruby < RDoc::Parser
1558
1558
  when TkNL, TkUNLESS_MOD, TkIF_MOD, TkSEMICOLON then
1559
1559
  container.ongoing_visibility = vis
1560
1560
  else
1561
- if vis_type == 'module_function' then
1561
+ new_methods = []
1562
+
1563
+ case vis_type
1564
+ when 'module_function' then
1562
1565
  args = parse_symbol_arg
1563
1566
  container.set_visibility_for args, :private, false
1564
1567
 
1565
- module_functions = []
1566
-
1567
1568
  container.methods_matching args do |m|
1568
1569
  s_m = m.dup
1569
1570
  s_m.record_location @top_level
1570
1571
  s_m.singleton = true
1571
- s_m.visibility = :public
1572
- module_functions << s_m
1572
+ new_methods << s_m
1573
1573
  end
1574
+ when 'public_class_method', 'private_class_method' then
1575
+ args = parse_symbol_arg
1574
1576
 
1575
- module_functions.each do |s_m|
1576
- case s_m
1577
- when RDoc::AnyMethod then
1578
- container.add_method s_m
1579
- when RDoc::Attr then
1580
- container.add_attribute s_m
1577
+ container.methods_matching args, true do |m|
1578
+ if m.parent != container then
1579
+ m = m.dup
1580
+ m.record_location @top_level
1581
+ new_methods << m
1581
1582
  end
1583
+
1584
+ m.visibility = vis
1582
1585
  end
1583
1586
  else
1584
1587
  args = parse_symbol_arg
1585
1588
  container.set_visibility_for args, vis, singleton
1586
1589
  end
1590
+
1591
+ new_methods.each do |method|
1592
+ case method
1593
+ when RDoc::AnyMethod then
1594
+ container.add_method method
1595
+ when RDoc::Attr then
1596
+ container.add_attribute method
1597
+ end
1598
+ method.visibility = vis
1599
+ end
1587
1600
  end
1588
1601
  end
1589
1602
 
@@ -418,7 +418,7 @@ The internal error was:
418
418
  @last_modified = setup_output_dir @options.op_dir, @options.force_update
419
419
  end
420
420
 
421
- start_time = Time.now
421
+ @start_time = Time.now
422
422
 
423
423
  file_info = parse_files @options.files
424
424
 
@@ -439,23 +439,10 @@ The internal error was:
439
439
 
440
440
  @generator = gen_klass.new @options
441
441
 
442
- Dir.chdir @options.op_dir do
443
- begin
444
- self.class.current = self
445
-
446
- unless @options.quiet then
447
- $stderr.puts "\nGenerating #{gen_klass.name.sub(/^.*::/, '')} format into #{Dir.pwd}..."
448
- end
449
-
450
- @generator.generate file_info
451
- update_output_dir ".", start_time, @last_modified
452
- ensure
453
- self.class.current = nil
454
- end
455
- end
442
+ generate file_info
456
443
  end
457
444
 
458
- unless @options.quiet or not @stats then
445
+ if @stats and (@options.coverage_report or not @options.quiet) then
459
446
  puts
460
447
  puts @stats.summary
461
448
  end
@@ -463,6 +450,28 @@ The internal error was:
463
450
  exit @stats.fully_documented? if @options.coverage_report
464
451
  end
465
452
 
453
+ ##
454
+ # Generates documentation for +file_info+ (from #parse_files) into the
455
+ # output dir using the generator selected
456
+ # by the RDoc options
457
+
458
+ def generate file_info
459
+ Dir.chdir @options.op_dir do
460
+ begin
461
+ self.class.current = self
462
+
463
+ unless @options.quiet then
464
+ $stderr.puts "\nGenerating #{@generator.class.name.sub(/^.*::/, '')} format into #{Dir.pwd}..."
465
+ end
466
+
467
+ @generator.generate file_info
468
+ update_output_dir '.', @start_time, @last_modified
469
+ ensure
470
+ self.class.current = nil
471
+ end
472
+ end
473
+ end
474
+
466
475
  ##
467
476
  # Removes a siginfo handler and replaces the previous
468
477
 
@@ -197,6 +197,13 @@ Options may also be set in the 'RI' environment variable.
197
197
 
198
198
  opt.separator nil
199
199
 
200
+ opt.on("--list", "-l",
201
+ "List classes ri knows about.") do
202
+ options[:list] = true
203
+ end
204
+
205
+ opt.separator nil
206
+
200
207
  opt.on("--[no-]profile",
201
208
  "Run with the ruby profiler") do |value|
202
209
  options[:profile] = value
@@ -331,6 +338,7 @@ Options may also be set in the 'RI' environment variable.
331
338
  require 'profile' if options[:profile]
332
339
 
333
340
  @names = options[:names]
341
+ @list = options[:list]
334
342
 
335
343
  @doc_dirs = []
336
344
  @stores = []
@@ -524,7 +532,10 @@ Options may also be set in the 'RI' environment variable.
524
532
  klass_name = method ? name : klass
525
533
 
526
534
  if name !~ /#|\./ then
527
- completions.push(*klasses.grep(/^#{klass_name}/))
535
+ completions = klasses.grep(/^#{klass_name}[^:]*$/)
536
+ completions.concat klasses.grep(/^#{name}[^:]*$/) if name =~ /::$/
537
+
538
+ completions << klass if classes.key? klass # to complete a method name
528
539
  elsif selector then
529
540
  completions << klass if classes.key? klass
530
541
  elsif classes.key? klass_name then
@@ -546,7 +557,7 @@ Options may also be set in the 'RI' environment variable.
546
557
  completions.push(*methods)
547
558
  end
548
559
 
549
- completions.sort
560
+ completions.sort.uniq
550
561
  end
551
562
 
552
563
  ##
@@ -878,9 +889,10 @@ Options may also be set in the 'RI' environment variable.
878
889
  end
879
890
 
880
891
  ##
881
- # Lists classes known to ri
892
+ # Lists classes known to ri starting with +names+. If +names+ is empty all
893
+ # known classes are shown.
882
894
 
883
- def list_known_classes
895
+ def list_known_classes names = []
884
896
  classes = []
885
897
 
886
898
  stores.each do |store|
@@ -889,9 +901,19 @@ Options may also be set in the 'RI' environment variable.
889
901
 
890
902
  classes = classes.flatten.uniq.sort
891
903
 
904
+ unless names.empty? then
905
+ filter = Regexp.union names.map { |name| /^#{name}/ }
906
+
907
+ classes = classes.grep filter
908
+ end
909
+
892
910
  page do |io|
893
911
  if paging? or io.tty? then
894
- io.puts "Classes and Modules known to ri:"
912
+ if names.empty? then
913
+ io.puts "Classes and Modules known to ri:"
914
+ else
915
+ io.puts "Classes and Modules starting with #{names.join ', '}:"
916
+ end
895
917
  io.puts
896
918
  end
897
919
 
@@ -910,7 +932,7 @@ Options may also be set in the 'RI' environment variable.
910
932
  methods = store.instance_methods[ancestor]
911
933
 
912
934
  if methods then
913
- matches = methods.grep(/^#{method}/)
935
+ matches = methods.grep(/^#{Regexp.escape method.to_s}/)
914
936
 
915
937
  matches = matches.map do |match|
916
938
  "#{klass}##{match}"
@@ -924,7 +946,7 @@ Options may also be set in the 'RI' environment variable.
924
946
  methods = store.class_methods[ancestor]
925
947
 
926
948
  next unless methods
927
- matches = methods.grep(/^#{method}/)
949
+ matches = methods.grep(/^#{Regexp.escape method.to_s}/)
928
950
 
929
951
  matches = matches.map do |match|
930
952
  "#{klass}::#{match}"
@@ -996,9 +1018,9 @@ Options may also be set in the 'RI' environment variable.
996
1018
 
997
1019
  case type
998
1020
  when '#', '::' then
999
- /^#{klass}#{type}#{name}$/
1021
+ /^#{klass}#{type}#{Regexp.escape name}$/
1000
1022
  else
1001
- /^#{klass}(#|::)#{name}$/
1023
+ /^#{klass}(#|::)#{Regexp.escape name}$/
1002
1024
  end
1003
1025
  end
1004
1026
 
@@ -1064,10 +1086,10 @@ Options may also be set in the 'RI' environment variable.
1064
1086
  def run
1065
1087
  if @list_doc_dirs then
1066
1088
  puts @doc_dirs
1067
- elsif @interactive then
1089
+ elsif @list then
1090
+ list_known_classes @names
1091
+ elsif @interactive or @names.empty? then
1068
1092
  interactive
1069
- elsif @names.empty? then
1070
- list_known_classes
1071
1093
  else
1072
1094
  display_names @names
1073
1095
  end