rdoc 3.11 → 3.12

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
@@ -0,0 +1,141 @@
1
+ = Developer Introduction
2
+
3
+ So you want to write a generator, fix a bug, or otherwise work with RDoc. This
4
+ document provides an overview of how RDoc works from parsing options to
5
+ generating output. Most of the documentation can be found in the specific
6
+ classes for each feature.
7
+
8
+ == Bugs
9
+
10
+ If you think you found a bug, file a ticket on the {issues
11
+ tracker}[https://github.com/rdoc/rdoc/issues] on github.
12
+
13
+ To get your bug fixed as fast as possible please include a sample file that
14
+ illustrates the problem or link to a repository and include steps to reproduce
15
+ the issue. Here are some examples of good issues:
16
+
17
+ * https://github.com/rdoc/rdoc/issues/55
18
+ * https://github.com/rdoc/rdoc/issues/61
19
+
20
+ == Plugins
21
+
22
+ When 'rdoc/rdoc' is loaded RDoc looks for 'rdoc/discover' files in your
23
+ installed gems. This can be used to load parsers, alternate generators, or
24
+ additional preprocessor directives. An rdoc plugin layout should look
25
+ something like this:
26
+
27
+ lib/rdoc/discover.rb
28
+ lib/my/rdoc/plugin.rb
29
+ # etc.
30
+
31
+ In your rdoc/discover.rb file you will want to wrap the loading of your plugin
32
+ in an RDoc version check like this:
33
+
34
+ begin
35
+ gem 'rdoc', '~> 3'
36
+ require 'my/rdoc/plugin'
37
+ rescue Gem::LoadError
38
+ end
39
+
40
+ === Plugin Types
41
+
42
+ In RDoc you can change the following behaviors:
43
+
44
+ * Add a parser for a new file format
45
+ * Add a new output generator
46
+ * Add a new markup directive
47
+ * Add a new type of documentation markup
48
+ * Add a new type of formatter
49
+
50
+ All of these are described below
51
+
52
+ == Option Parsing
53
+
54
+ Option parsing is handled by RDoc::Options. When you're writing a generator
55
+ you can provide the user with extra options by providing a class method
56
+ +setup_options+. The option parser will call this after your generator is
57
+ loaded. See RDoc::Generator for details.
58
+
59
+ == File Parsing
60
+
61
+ After options are parsed, RDoc parses files from the files and directories in
62
+ ARGV. RDoc compares the filename against what each parser claims it can parse
63
+ via RDoc::Parser#parse_files_matching. For example, RDoc::Parser::C can parse
64
+ C files, C headers, C++ files, C++ headers and yacc grammars.
65
+
66
+ Once a matching parser class is found it is instantiated and +scan+ is called.
67
+ The parser needs to extract documentation from the file and add it to the RDoc
68
+ document tree. Usually this involves starting at the root and adding a class
69
+ or a module (RDoc::TopLevel#add_class and RDoc::TopLevel#add_module) and
70
+ proceeding to add classes, modules and methods to each nested item.
71
+
72
+ When the parsers are finished the document tree is cleaned up to remove
73
+ dangling references to aliases and includes that were not found (and may exist
74
+ in a separate library) through RDoc::ClassModule#complete.
75
+
76
+ To write your own parser for a new file format see RDoc::Parser.
77
+
78
+ === Documentation Tree
79
+
80
+ The parsers build a documentation tree that is composed of RDoc::CodeObject and
81
+ its subclasses. There are various methods to walk the tree to extract
82
+ information, see RDoc::Context and its subclasses.
83
+
84
+ Within a class or module, attributes, methods and constants are divided into
85
+ sections. The section represents a functional grouping of parts of the class.
86
+ TomDoc uses the sections "Public", "Internal" and "Deprecated". The sections
87
+ can be enumerated using RDoc::Context#each_section.
88
+
89
+ == Output Generation
90
+
91
+ An RDoc generator turns the documentation tree into some other kind of output.
92
+ RDoc comes with an HTML generator (RDoc::Generator::Darkfish) and an RI
93
+ database generator (RDoc::Generator::RI). The output a generator creates does
94
+ not have to be human-readable.
95
+
96
+ To create your own generator see RDoc::Generator.
97
+
98
+ === Comments
99
+
100
+ In RDoc 3.10 and newer the comment on an RDoc::CodeObject is now an
101
+ RDoc::Comment object instead of a String. This is to support various
102
+ documentation markup formats like rdoc, TomDoc and rd. The comments are
103
+ normalized to remove comment markers and remove indentation then parsed lazily
104
+ via RDoc::Comment#document to create a generic markup tree that can be
105
+ processed by a formatter.
106
+
107
+ To add your own markup format see RDoc::Markup@Other+directives
108
+
109
+ ==== Formatters
110
+
111
+ To transform a comment into some form of output an RDoc::Markup::Formatter
112
+ subclass is used like RDoc::Markup::ToHtml. A formatter is a visitor that
113
+ walks a parsed comment tree (an RDoc::Markup::Document) of any format. To help
114
+ write a formatter RDoc::Markup::FormatterTestCase exists for generic parsers,
115
+ and RDoc::Markup::TextFormatterTestCase which contains extra test cases for
116
+ text-type output (like +ri+ output).
117
+
118
+ RDoc ships with formatters that will turn a comment into HTML, rdoc-markup-like
119
+ text, ANSI or terminal backspace highlighted text, HTML, cross-referenced HTML,
120
+ an HTML snippet free of most markup, an HTML label for use in id attributes, a
121
+ table-of-contents page, and text with only code blocks.
122
+
123
+ The output of the formatter does not need to be text or text-like.
124
+ RDoc::Markup::ToLabel creates an HTML-safe label for use in an HTML id
125
+ attribute. A formatter could count the number of words and the average word
126
+ length for a comment, for example.
127
+
128
+ ==== Directives
129
+
130
+ For comments in markup you can add new directives (:nodoc: is a directive).
131
+ Directives may replace text or store it off for later use.
132
+
133
+ See RDoc::Markup::PreProcess::register for details.
134
+
135
+ === JSONIndex
136
+
137
+ RDoc contains a special generator, RDoc::Generator::JSONIndex, which creates a
138
+ JSON-based search index and includes a search engine for use with HTML output.
139
+ This generator can be used to add searching to any HTML output and is designed
140
+ to be called from inside an HTML generator.
141
+
@@ -1,4 +1,35 @@
1
- === 3.11 / 2011/10-17
1
+ === 3.12 / 2011-12-15
2
+
3
+ * Minor enhancements
4
+ * Added DEVELOPERS document which contains an overview of how RDoc works and
5
+ how to add new features to RDoc.
6
+ * Improved title for HTML output to include <code>--title</code> in the
7
+ title element.
8
+ * <code>rdoc --pipe</code> now understands <code>--markup</code>.
9
+ * RDoc now supports irc-scheme hyperlinks. Issue #83 by trans.
10
+
11
+ * Bug fixes
12
+ * Fix title on HTML output for pages.
13
+ * Fixed parsing of non-indented HEREDOC.
14
+ * Fixed parsing of <code>%w[]</code> and other % literals. Issue #84 by
15
+ Erik Hollensbe
16
+ * Fixed arrow replacement in HTML output munging the spaceship operator.
17
+ Issue #85 by eclectic923.
18
+ * Verbatim sections with ERB that match the ruby code whitelist are no
19
+ longer syntax-highlighted. Issue #86 by eclectic923
20
+ * Line endings on windows are normalized immediately after reading with
21
+ binmode. Issue #87 by Usa Nakamura
22
+ * RDoc better understands directives for comments. Comment directives can
23
+ now be found anywhere in multi-line comments. Issue #90 by Ryan Davis
24
+ * Tidy links to methods show the label again. Issue #88 by Simon Chiang
25
+ * RDoc::Parser::C can now find comments directly above
26
+ +rb_define_class_under+. Issue #89 by Enrico
27
+ * In rdoc, backspace and ansi formatters, labels and notes without bodies
28
+ are now shown.
29
+ * In rdoc, backspace and ansi formatters, whitespace between label or note
30
+ and the colon is now stripped.
31
+
32
+ === 3.11 / 2011-10-17
2
33
 
3
34
  * Bug fixes
4
35
  * Avoid parsing TAGS files included in gems. Issue #81 by Santiago
@@ -1,5 +1,6 @@
1
1
  .autotest
2
2
  .document
3
+ DEVELOPERS.rdoc
3
4
  History.rdoc
4
5
  LEGAL.rdoc
5
6
  LICENSE.rdoc
@@ -43,7 +43,7 @@ To generate documentation programmatically:
43
43
  == Bugs
44
44
 
45
45
  If you find a bug, please report it at the RDoc project's
46
- {issues tracker}[https://github.com/rdoc/rdoc/issues] on github
46
+ {issues tracker}[https://github.com/rdoc/rdoc/issues] on github.
47
47
 
48
48
  == License
49
49
 
data/Rakefile CHANGED
@@ -41,6 +41,7 @@ Depending on your version of ruby, you may need to install ruby rdoc/ri data:
41
41
  self.history_file = 'History.rdoc'
42
42
  self.testlib = :minitest
43
43
  self.extra_rdoc_files += %w[
44
+ DEVELOPERS.rdoc
44
45
  History.rdoc
45
46
  LICENSE.rdoc
46
47
  LEGAL.rdoc
data/TODO.rdoc CHANGED
@@ -1,7 +1,9 @@
1
- Some file contains some things that might happen in RDoc, or might not
1
+ This file contains some things that might happen in RDoc, or might not.
2
+ Forward Looking Statements applies.
2
3
 
3
- === 3.11
4
+ === 3.next
4
5
 
6
+ * Update LICENSE to match ruby's switch
5
7
  * Reload the RDoc tree from an RI store
6
8
  * Re-run generators
7
9
  * Parse only changed files (like in ruby)
@@ -9,11 +11,13 @@ Some file contains some things that might happen in RDoc, or might not
9
11
  statistics.
10
12
  * Link to the parent-class implementation of methods that use super
11
13
  * Add direct accessor to RDoc::Options to RDoc::Task
12
- * Remove Public in HTML output if there are only public methods
13
- * Method markup support for rd documentation
14
+ * Remove "Public" in HTML output if there are only public methods
15
+ * Method markup support for rd documentation (per rd syntax)
14
16
  * Improve SIGINFO handling
15
17
  * Global variable support
16
18
  * Page support for ri
19
+ * Provide the code_object to directive handlers
20
+ * Add markup parser documentation to DEVELOPERS.rdoc
17
21
 
18
22
  === 4
19
23
 
@@ -24,6 +24,7 @@ $DEBUG_RDOC = nil
24
24
  #
25
25
  # == Roadmap
26
26
  #
27
+ # * If you think you found a bug in RDoc see DEVELOPERS@Bugs
27
28
  # * If you want to use RDoc to create documentation for your Ruby source files,
28
29
  # see RDoc::Markup and refer to <tt>rdoc --help</tt> for command line
29
30
  # usage.
@@ -39,6 +40,7 @@ $DEBUG_RDOC = nil
39
40
  # * If you want to make an RDoc plugin such as a generator or directive
40
41
  # handler see RDoc::RDoc.
41
42
  # * If you want to write your own output generator see RDoc::Generator.
43
+ # * If you want an overview of how RDoc works see DEVELOPERS
42
44
  #
43
45
  # == Summary
44
46
  #
@@ -106,7 +108,7 @@ module RDoc
106
108
  ##
107
109
  # RDoc version you are using
108
110
 
109
- VERSION = '3.11'
111
+ VERSION = '3.12'
110
112
 
111
113
  ##
112
114
  # Method visibilities
@@ -882,6 +882,8 @@ class RDoc::Context < RDoc::CodeObject
882
882
 
883
883
  ##
884
884
  # Instance methods
885
+ #--
886
+ # TODO rename to instance_methods
885
887
 
886
888
  def instance_method_list
887
889
  @instance_method_list ||= method_list.reject { |a| a.singleton }
@@ -18,6 +18,7 @@ module RDoc::Encoding
18
18
 
19
19
  def self.read_file filename, encoding, force_transcode = false
20
20
  content = open filename, "rb" do |f| f.read end
21
+ content.gsub!("\r\n", "\n") if RUBY_PLATFORM =~ /mswin|mingw/
21
22
 
22
23
  utf8 = content.sub!(/\A\xef\xbb\xbf/, '')
23
24
 
@@ -4,7 +4,7 @@
4
4
  # generator RDoc::Generator::Darkfish and an ri data generator
5
5
  # RDoc::Generator::RI.
6
6
  #
7
- # = Registering a Generator
7
+ # == Registering a Generator
8
8
  #
9
9
  # Generators are registered by calling RDoc::RDoc.add_generator with the class
10
10
  # of the generator:
@@ -13,7 +13,7 @@
13
13
  # RDoc::RDoc.add_generator self
14
14
  # end
15
15
  #
16
- # = Adding Options to +rdoc+
16
+ # == Adding Options to +rdoc+
17
17
  #
18
18
  # Before option processing in +rdoc+, RDoc::Options will call ::setup_options
19
19
  # on the generator class with an RDoc::Options instance. The generator can
@@ -23,7 +23,7 @@
23
23
  # You can extend the RDoc::Options instance with additional accessors for your
24
24
  # generator.
25
25
  #
26
- # = Generator Instantiation
26
+ # == Generator Instantiation
27
27
  #
28
28
  # After parsing, RDoc::RDoc will instantiate a generator by calling
29
29
  # #initialize with an RDoc::Options instance.
@@ -283,7 +283,7 @@ class RDoc::Generator::Darkfish
283
283
  # suppress 1.9.3 warning
284
284
  rel_prefix = rel_prefix = @outputdir.relative_path_from(out_file.dirname)
285
285
  svninfo = svninfo = self.get_svninfo(klass)
286
- @title = "#{klass.type.capitalize}: #{klass.full_name}"
286
+ @title = "#{klass.type} #{klass.full_name} - #{@options.title}"
287
287
 
288
288
  debug_msg " rendering #{out_file}"
289
289
  render_template template_file, out_file do |io| binding end
@@ -302,7 +302,9 @@ class RDoc::Generator::Darkfish
302
302
  def generate_file_files
303
303
  page_file = @template_dir + 'page.rhtml'
304
304
  fileinfo_file = @template_dir + 'fileinfo.rhtml'
305
- template_file = @template_dir + 'filepage.rhtml' unless
305
+
306
+ # for legacy templates
307
+ filepage_file = @template_dir + 'filepage.rhtml' unless
306
308
  page_file.exist? or fileinfo_file.exist?
307
309
 
308
310
  return unless
@@ -312,12 +314,13 @@ class RDoc::Generator::Darkfish
312
314
  out_file = nil
313
315
 
314
316
  @files.each do |file|
315
- out_file = @outputdir + file.path
317
+ template_file = nil
318
+ out_file = @outputdir + file.path
316
319
  debug_msg " working on %s (%s)" % [file.full_name, out_file]
317
320
  # suppress 1.9.3 warning
318
321
  rel_prefix = rel_prefix = @outputdir.relative_path_from(out_file.dirname)
319
322
 
320
- unless template_file then
323
+ unless filepage_file then
321
324
  if file.text? then
322
325
  next unless page_file.exist?
323
326
  template_file = page_file
@@ -325,10 +328,13 @@ class RDoc::Generator::Darkfish
325
328
  else
326
329
  next unless fileinfo_file.exist?
327
330
  template_file = fileinfo_file
328
- @title = "File: #{file.base_name} [#{@options.title}]"
331
+ @title = "File: #{file.base_name}"
329
332
  end
330
333
  end
331
334
 
335
+ @title += " - #{@options.title}"
336
+ template_file ||= filepage_file
337
+
332
338
  render_template template_file, out_file do |io| binding end
333
339
  end
334
340
  rescue => e
@@ -351,7 +357,7 @@ class RDoc::Generator::Darkfish
351
357
  out_file = @outputdir + 'table_of_contents.html'
352
358
  # suppress 1.9.3 warning
353
359
  rel_prefix = rel_prefix = @outputdir.relative_path_from(out_file.dirname)
354
- @title = "Table of Contents"
360
+ @title = "Table of Contents - #{@options.title}"
355
361
 
356
362
  render_template template_file, out_file do |io| binding end
357
363
  rescue => e
@@ -105,7 +105,9 @@
105
105
  <% method.call_seq.strip.split("\n").each_with_index do |call_seq, i| %>
106
106
  <div class="method-heading">
107
107
  <span class="method-callseq">
108
- <%= h(call_seq.strip.gsub( /^\w+\./m, '')).gsub(/[-=]&gt;/, '&rarr;') %>
108
+ <%= h(call_seq.strip.
109
+ gsub( /^\w+\./m, '')).
110
+ gsub(/(.*)[-=]&gt;/, '\1&rarr;') %>
109
111
  </span>
110
112
  <% if i == 0 then %>
111
113
  <span class="method-click-advice">click to toggle source</span>
@@ -6,7 +6,12 @@
6
6
  # Directives can be escaped by preceding them with a backslash.
7
7
  #
8
8
  # RDoc plugin authors can register additional directives to be handled by
9
- # using RDoc::Markup::PreProcess::register
9
+ # using RDoc::Markup::PreProcess::register.
10
+ #
11
+ # Any directive that is not built-in to RDoc (including those registered via
12
+ # plugins) will be stored in the metadata hash on the CodeObject the comment
13
+ # is attached to. See RDoc::Markup@Directives for the list of built-in
14
+ # directives.
10
15
 
11
16
  class RDoc::Markup::PreProcess
12
17
 
@@ -36,6 +41,13 @@ class RDoc::Markup::PreProcess
36
41
  # Registers +directive+ as one handled by RDoc. If a block is given the
37
42
  # directive will be replaced by the result of the block, otherwise the
38
43
  # directive will be removed from the processed text.
44
+ #
45
+ # The block will be called with the directive name and the directive
46
+ # parameter:
47
+ #
48
+ # RDoc::Markup::PreProcess.register 'my-directive' do |directive, param|
49
+ # # replace text, etc.
50
+ # end
39
51
 
40
52
  def self.register directive, &block
41
53
  @registered[directive] = block
@@ -42,7 +42,7 @@ class RDoc::Markup::Raw
42
42
  end
43
43
 
44
44
  def pretty_print q # :nodoc:
45
- self.class.name =~ /.*::(\w{4})/i
45
+ self.class.name =~ /.*::(\w{1,4})$/i
46
46
 
47
47
  q.group 2, "[#{$1.downcase}: ", ']' do
48
48
  q.seplist @parts do |part|
@@ -32,6 +32,11 @@ class RDoc::Markup::ToAnsi < RDoc::Markup::ToRdoc
32
32
  when :BULLET then
33
33
  2
34
34
  when :NOTE, :LABEL then
35
+ if @prefix then
36
+ @res << @prefix.strip
37
+ @prefix = nil
38
+ end
39
+
35
40
  @res << "\n" unless res.length == 1
36
41
  2
37
42
  else
@@ -51,7 +56,7 @@ class RDoc::Markup::ToAnsi < RDoc::Markup::ToRdoc
51
56
  when :BULLET then
52
57
  '*'
53
58
  when :NOTE, :LABEL then
54
- attributes(list_item.label) + ":\n"
59
+ attributes(list_item.label).strip + ":\n"
55
60
  else
56
61
  @list_index.last.to_s + '.'
57
62
  end
@@ -75,7 +75,8 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
75
75
  @th = nil
76
76
 
77
77
  # external links
78
- @markup.add_special(/((link:|https?:|mailto:|ftp:|www\.)\S+\w)/, :HYPERLINK)
78
+ @markup.add_special(/((link:|https?:|mailto:|ftp:|irc:|www\.)\S+\w)/,
79
+ :HYPERLINK)
79
80
 
80
81
  # internal links
81
82
  @markup.add_special(/rdoc-[a-z]+:\S+/, :RDOCLINK)
@@ -378,7 +379,8 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
378
379
  # Returns true if Ripper is available it can create a sexp from +text+
379
380
 
380
381
  def parseable? text
381
- text =~ /\b(def|class|module|require)\b|=>|\{\s?\||do \|/
382
+ text =~ /\b(def|class|module|require)\b|=>|\{\s?\||do \|/ and
383
+ text !~ /<%|%>/
382
384
  end
383
385
 
384
386
  ##
@@ -124,6 +124,8 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
124
124
  # Creates an HTML link to +name+ with the given +text+.
125
125
 
126
126
  def link name, text
127
+ original_name = name
128
+
127
129
  if name =~ /(.*[^#:])@/ then
128
130
  name = $1
129
131
  label = $'
@@ -131,7 +133,8 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
131
133
 
132
134
  ref = @cross_reference.resolve name, text
133
135
 
134
- text = ref.output_name @context if RDoc::MethodAttr === ref and not label
136
+ text = ref.output_name @context if
137
+ RDoc::MethodAttr === ref and text == original_name
135
138
 
136
139
  case ref
137
140
  when String then
@@ -103,6 +103,11 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
103
103
  when :BULLET then
104
104
  2
105
105
  when :NOTE, :LABEL then
106
+ if @prefix then
107
+ @res << @prefix.strip
108
+ @prefix = nil
109
+ end
110
+
106
111
  @res << "\n"
107
112
  2
108
113
  else
@@ -122,7 +127,7 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
122
127
 
123
128
  case type
124
129
  when :NOTE, :LABEL then
125
- bullet = attributes(list_item.label) + ":\n"
130
+ bullet = attributes(list_item.label).strip + ":\n"
126
131
  @prefix = ' ' * @indent
127
132
  @indent += 2
128
133
  @prefix << bullet + (' ' * @indent)
@@ -249,8 +254,7 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
249
254
  # prefix for later consumption.
250
255
 
251
256
  def use_prefix
252
- prefix = @prefix
253
- @prefix = nil
257
+ prefix, @prefix = @prefix, nil
254
258
  @res << prefix if prefix
255
259
 
256
260
  prefix
@@ -49,6 +49,7 @@ class RDoc::Markup::Verbatim < RDoc::Markup::Raw
49
49
  # Is this verbatim section ruby code?
50
50
 
51
51
  def ruby?
52
+ @format ||= nil # TODO for older ri data, switch the tree to marshal_dump
52
53
  @format == :ruby
53
54
  end
54
55
 
@@ -1,5 +1,3 @@
1
- require 'cgi'
2
-
3
1
  ##
4
2
  # Abstract class representing either a method or an attribute.
5
3
 
@@ -261,6 +259,8 @@ class RDoc::MethodAttr < RDoc::CodeObject
261
259
  # HTML id-friendly method/attribute name
262
260
 
263
261
  def html_name
262
+ require 'cgi'
263
+
264
264
  CGI.escape(@name.gsub('-', '-2D')).gsub('%','-').sub(/^-/, '')
265
265
  end
266
266
 
@@ -572,6 +572,9 @@ class RDoc::Parser::C < RDoc::Parser
572
572
  elsif @content =~ %r%((?>/\*.*?\*/\s+))
573
573
  ([\w\.\s]+\s* = \s+)?rb_define_(class|module).*?"(#{class_name})"%xm then
574
574
  comment = $1
575
+ elsif @content =~ %r%((?>/\*.*?\*/\s+))
576
+ ([\w\.\s]+\s* = \s+)?rb_define_(class|module)_under.*?"(#{class_name.split('::').last})"%xm then
577
+ comment = $1
575
578
  else
576
579
  comment = ''
577
580
  end
@@ -663,6 +663,8 @@ class RDoc::Parser::Ruby < RDoc::Parser
663
663
  return false
664
664
  end
665
665
 
666
+ value = ''
667
+ con = RDoc::Constant.new name, value, comment
666
668
  nest = 0
667
669
  get_tkread
668
670
 
@@ -690,6 +692,9 @@ class RDoc::Parser::Ruby < RDoc::Parser
690
692
  (@scanner.lex_state == EXPR_END || !@scanner.continue) then
691
693
  unget_tk tk
692
694
  break
695
+ else
696
+ unget_tk tk
697
+ read_documentation_modifiers con, RDoc::CONSTANT_MODIFIERS
693
698
  end
694
699
  when TkCONSTANT then
695
700
  rhs_name << tk.name
@@ -721,7 +726,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
721
726
  res = get_tkread.gsub(/^[ \t]+/, '').strip
722
727
  res = "" if res == ";"
723
728
 
724
- con = RDoc::Constant.new name, res, comment
729
+ value.replace res
725
730
  con.record_location @top_level
726
731
  con.offset = offset
727
732
  con.line = line_no
@@ -5,38 +5,29 @@ require 'fileutils'
5
5
  require 'time'
6
6
 
7
7
  ##
8
- # Encapsulate the production of rdoc documentation. Basically you can use this
9
- # as you would invoke rdoc from the command line:
8
+ # This is the driver for generating RDoc output. It file parsing and
9
+ # generation of output.
10
10
  #
11
- # rdoc = RDoc::RDoc.new
12
- # rdoc.document(args)
13
- #
14
- # Where +args+ is an array of strings, each corresponding to an argument you'd
15
- # give rdoc on the command line. See <tt>rdoc --help<tt> for details.
11
+ # To use this class to generate RDoc output via the API, the recommended way
12
+ # is:
16
13
  #
17
- # = Plugins
18
- #
19
- # When you <tt>require 'rdoc/rdoc'</tt> RDoc looks for 'rdoc/discover' files
20
- # in your installed gems. This can be used to load alternate generators or
21
- # add additional preprocessor directives.
22
- #
23
- # You will want to wrap your plugin loading in an RDoc version check.
24
- # Something like:
14
+ # rdoc = RDoc::RDoc.new
15
+ # options = rdoc.load_options # returns an RDoc::Options instance
16
+ # # set extra options
17
+ # rdoc.document options
25
18
  #
26
- # begin
27
- # gem 'rdoc', '~> 3'
28
- # require 'path/to/my/awesome/rdoc/plugin'
29
- # rescue Gem::LoadError
30
- # end
19
+ # You can also generate output like the +rdoc+ executable:
31
20
  #
32
- # The most obvious plugin type is a new output generator. See RDoc::Generator
33
- # for details.
21
+ # rdoc = RDoc::RDoc.new
22
+ # rdoc.document argv
34
23
  #
35
- # You can also hook into RDoc::Markup to add new directives (:nodoc: is a
36
- # directive). See RDoc::Markup::PreProcess::register for details.
24
+ # Where +argv+ is an array of strings, each corresponding to an argument you'd
25
+ # give rdoc on the command line. See <tt>rdoc --help<tt> for details.
37
26
 
38
27
  class RDoc::RDoc
39
28
 
29
+ @current = nil
30
+
40
31
  ##
41
32
  # This is the list of supported output generators
42
33
 
@@ -139,7 +130,11 @@ class RDoc::RDoc
139
130
  def handle_pipe
140
131
  @html = RDoc::Markup::ToHtml.new
141
132
 
142
- out = @html.convert $stdin.read
133
+ parser = RDoc::Text::MARKUP_FORMAT[@options.markup]
134
+
135
+ document = parser.parse $stdin.read
136
+
137
+ out = @html.convert document
143
138
 
144
139
  $stdout.write out
145
140
  end
@@ -491,7 +491,7 @@ class RDoc::RubyLex
491
491
  |op, io|
492
492
  tk = nil
493
493
  if @lex_state != EXPR_END && @lex_state != EXPR_CLASS &&
494
- (@lex_state != EXPR_ARG || @space_seen)
494
+ (@lex_state != EXPR_ARG || @space_seen)
495
495
  c = peek(0)
496
496
  if /\S/ =~ c && (/["'`]/ =~ c || /\w/ =~ c || c == "-")
497
497
  tk = identify_here_document
@@ -1013,7 +1013,7 @@ class RDoc::RubyLex
1013
1013
  doc = '"'
1014
1014
  while l = gets
1015
1015
  l = l.sub(/(:?\r)?\n\z/, "\n")
1016
- if (indent ? l.strip : l) == quoted
1016
+ if (indent ? l.strip : l.chomp) == quoted
1017
1017
  break
1018
1018
  end
1019
1019
  doc << l
@@ -1032,13 +1032,14 @@ class RDoc::RubyLex
1032
1032
  end
1033
1033
 
1034
1034
  def identify_quotation
1035
- ch = getc
1036
- if lt = PERCENT_LTYPE[ch]
1035
+ type = ch = getc
1036
+ if lt = PERCENT_LTYPE[type]
1037
1037
  ch = getc
1038
- elsif ch =~ /\W/
1038
+ elsif type =~ /\W/
1039
+ type = nil
1039
1040
  lt = "\""
1040
1041
  else
1041
- raise Error, "unknown type of %string #{ch.inspect}"
1042
+ raise Error, "unknown type of %string #{type.inspect}"
1042
1043
  end
1043
1044
  # if ch !~ /\W/
1044
1045
  # ungetc
@@ -1046,7 +1047,7 @@ class RDoc::RubyLex
1046
1047
  # end
1047
1048
  #@ltype = lt
1048
1049
  @quoted = ch unless @quoted = PERCENT_PAREN[ch]
1049
- identify_string(lt, @quoted)
1050
+ identify_string(lt, @quoted, type)
1050
1051
  end
1051
1052
 
1052
1053
  def identify_number(op = "")
@@ -1157,17 +1158,17 @@ class RDoc::RubyLex
1157
1158
  Token(type, num)
1158
1159
  end
1159
1160
 
1160
- def identify_string(ltype, quoted = ltype)
1161
+ def identify_string(ltype, quoted = ltype, type = nil)
1161
1162
  close = PERCENT_PAREN.values.include?(quoted)
1162
1163
  @ltype = ltype
1163
1164
  @quoted = quoted
1164
1165
 
1165
- str = if ltype == quoted then
1166
+ str = if ltype == quoted and %w[" '].include? ltype then
1166
1167
  ltype.dup
1167
1168
  elsif RUBY_VERSION > '1.9' then
1168
- "%#{PERCENT_LTYPE.key ltype}#{PERCENT_PAREN_REV[quoted]}"
1169
+ "%#{type or PERCENT_LTYPE.key ltype}#{PERCENT_PAREN_REV[quoted]}"
1169
1170
  else
1170
- "%#{PERCENT_LTYPE.index ltype}#{PERCENT_PAREN_REV[quoted]}"
1171
+ "%#{type or PERCENT_LTYPE.index ltype}#{PERCENT_PAREN_REV[quoted]}"
1171
1172
  end
1172
1173
 
1173
1174
  subtype = nil
@@ -50,11 +50,6 @@ Regular expressions (<i>regexp</i>s) are patterns which describe the
50
50
  contents of a string.
51
51
  EXPECTED
52
52
 
53
- # FIXME 1.9 fix on windoze
54
- # preprocessor uses binread, so line endings are \r\n
55
- expected.gsub!("\n", "\r\n") if
56
- RUBY_VERSION < "1.9.3" && RUBY_PLATFORM =~ /mswin|mingw/
57
-
58
53
  assert_equal expected, content
59
54
  end
60
55
 
@@ -74,11 +69,6 @@ contents of a string.
74
69
 
75
70
  expected = "?\n"
76
71
 
77
- # FIXME 1.9 fix on windoze
78
- # preprocessor uses binread, so line endings are \r\n
79
- expected.gsub!("\n", "\r\n") if
80
- RUBY_VERSION < "1.9.3" && RUBY_PLATFORM =~ /mswin|mingw/
81
-
82
72
  assert_equal expected, content
83
73
  end
84
74
 
@@ -21,5 +21,9 @@ class TestRDocMarkupRaw < RDoc::TestCase
21
21
  assert_equal @RM::Raw.new('hi', 'there'), @p
22
22
  end
23
23
 
24
+ def test_pretty_print
25
+ assert_equal '[raw: ]', mu_pp(@p)
26
+ end
27
+
24
28
  end
25
29
 
@@ -64,7 +64,7 @@ class TestRDocMarkupToAnsi < RDoc::Markup::TextFormatterTestCase
64
64
  end
65
65
 
66
66
  def accept_list_item_end_label
67
- assert_equal "\e[0m", @to.res.join
67
+ assert_equal "\e[0mcat:\n", @to.res.join
68
68
  assert_equal 0, @to.indent, 'indent'
69
69
  end
70
70
 
@@ -74,7 +74,7 @@ class TestRDocMarkupToAnsi < RDoc::Markup::TextFormatterTestCase
74
74
  end
75
75
 
76
76
  def accept_list_item_end_note
77
- assert_equal "\e[0m", @to.res.join
77
+ assert_equal "\e[0mcat:\n", @to.res.join
78
78
  assert_equal 0, @to.indent, 'indent'
79
79
  end
80
80
 
@@ -325,5 +325,24 @@ words words words words
325
325
  assert_equal expected, @to.end_accepting
326
326
  end
327
327
 
328
+ # functional test
329
+ def test_convert_list_note
330
+ note_list = <<-NOTE_LIST
331
+ foo ::
332
+ bar ::
333
+ hi
334
+ NOTE_LIST
335
+
336
+ expected = <<-EXPECTED
337
+ \e[0m
338
+ foo:
339
+ bar:
340
+ hi
341
+
342
+ EXPECTED
343
+
344
+ assert_equal expected, @to.convert(note_list)
345
+ end
346
+
328
347
  end
329
348
 
@@ -65,7 +65,7 @@ class TestRDocMarkupToBs < RDoc::Markup::TextFormatterTestCase
65
65
  end
66
66
 
67
67
  def accept_list_item_end_label
68
- assert_equal "\n", @to.res.join
68
+ assert_equal "cat:\n", @to.res.join
69
69
  assert_equal 0, @to.indent, 'indent'
70
70
  end
71
71
 
@@ -75,7 +75,7 @@ class TestRDocMarkupToBs < RDoc::Markup::TextFormatterTestCase
75
75
  end
76
76
 
77
77
  def accept_list_item_end_note
78
- assert_equal "\n", @to.res.join
78
+ assert_equal "cat:\n", @to.res.join
79
79
  assert_equal 0, @to.indent, 'indent'
80
80
  end
81
81
 
@@ -389,6 +389,12 @@ class TestRDocMarkupToHtml < RDoc::Markup::FormatterTestCase
389
389
  assert_equal '&lt;&gt;', @to.convert_string('<>')
390
390
  end
391
391
 
392
+ def test_convert_HYPERLINK_irc
393
+ result = @to.convert 'irc://irc.freenode.net/#ruby-lang'
394
+
395
+ assert_equal "\n<p><a href=\"irc://irc.freenode.net/#ruby-lang\">irc.freenode.net/#ruby-lang</a></p>\n", result
396
+ end
397
+
392
398
  def test_convert_RDOCLINK_label_label
393
399
  result = @to.convert 'rdoc-label:label-One'
394
400
 
@@ -419,6 +425,12 @@ class TestRDocMarkupToHtml < RDoc::Markup::FormatterTestCase
419
425
  assert_equal "\n<p><a href=\"#foottext-1\">foo</a></p>\n", result
420
426
  end
421
427
 
428
+ def test_convert_TIDYLINK_irc
429
+ result = @to.convert '{ruby-lang}[irc://irc.freenode.net/#ruby-lang]'
430
+
431
+ assert_equal "\n<p><a href=\"irc://irc.freenode.net/#ruby-lang\">ruby-lang</a></p>\n", result
432
+ end
433
+
422
434
  def test_gen_url
423
435
  assert_equal '<a href="example">example</a>',
424
436
  @to.gen_url('link:example', 'example')
@@ -450,6 +462,14 @@ class TestRDocMarkupToHtml < RDoc::Markup::FormatterTestCase
450
462
  assert_equal '<a href="README.txt">README.txt</a>', link
451
463
  end
452
464
 
465
+ def test_handle_special_HYPERLINK_irc
466
+ special = RDoc::Markup::Special.new 0, 'irc://irc.freenode.net/#ruby-lang'
467
+
468
+ link = @to.handle_special_HYPERLINK special
469
+
470
+ assert_equal '<a href="irc://irc.freenode.net/#ruby-lang">irc.freenode.net/#ruby-lang</a>', link
471
+ end
472
+
453
473
  def test_list_verbatim_2
454
474
  str = "* one\n verb1\n verb2\n* two\n"
455
475
 
@@ -476,6 +496,7 @@ verb2</pre>
476
496
  assert @to.parseable?('x do |y| ... end'), 'do |x|'
477
497
  refute @to.parseable?('* 1'), '* 1'
478
498
  refute @to.parseable?('# only a comment'), '# only a comment'
499
+ refute @to.parseable?('<% require "foo" %>'), 'ERB'
479
500
  end
480
501
 
481
502
  def test_to_html
@@ -112,7 +112,7 @@ class TestRDocMarkupToHtmlCrossref < XrefTestCase
112
112
  def test_handle_special_CROSSREF_show_hash_false
113
113
  @to.show_hash = false
114
114
 
115
- assert_equal "<a href=\"C1.html#method-i-m\">#m</a>",
115
+ assert_equal "<a href=\"C1.html#method-i-m\">m</a>",
116
116
  SPECIAL('#m')
117
117
  end
118
118
 
@@ -149,6 +149,10 @@ class TestRDocMarkupToHtmlCrossref < XrefTestCase
149
149
 
150
150
  assert_equal '<a href="C4.html">tidy</a>', link
151
151
 
152
+ link = @to.handle_special_TIDYLINK tidy 'C1#m'
153
+
154
+ assert_equal '<a href="C1.html#method-i-m">tidy</a>', link
155
+
152
156
  link = @to.handle_special_TIDYLINK tidy 'README.txt'
153
157
 
154
158
  assert_equal '<a href="README_txt.html">tidy</a>', link
@@ -64,7 +64,7 @@ class TestRDocMarkupToRDoc < RDoc::Markup::TextFormatterTestCase
64
64
  end
65
65
 
66
66
  def accept_list_item_end_label
67
- assert_equal "\n", @to.res.join
67
+ assert_equal "cat:\n", @to.res.join
68
68
  assert_equal 0, @to.indent, 'indent'
69
69
  end
70
70
 
@@ -74,7 +74,7 @@ class TestRDocMarkupToRDoc < RDoc::Markup::TextFormatterTestCase
74
74
  end
75
75
 
76
76
  def accept_list_item_end_note
77
- assert_equal "\n", @to.res.join
77
+ assert_equal "cat:\n", @to.res.join
78
78
  assert_equal 0, @to.indent, 'indent'
79
79
  end
80
80
 
@@ -324,6 +324,25 @@ words words words words
324
324
  assert_equal expected, @to.end_accepting
325
325
  end
326
326
 
327
+ # functional test
328
+ def test_convert_list_note
329
+ note_list = <<-NOTE_LIST
330
+ foo ::
331
+ bar ::
332
+ hi
333
+ NOTE_LIST
334
+
335
+ expected = <<-EXPECTED
336
+
337
+ foo:
338
+ bar:
339
+ hi
340
+
341
+ EXPECTED
342
+
343
+ assert_equal expected, @to.convert(note_list)
344
+ end
345
+
327
346
  def test_accept_indented_paragraph
328
347
  ip = RDoc::Markup::IndentedParagraph.new 2, 'cats are cool'
329
348
 
@@ -701,6 +701,41 @@ Init_Foo(void) {
701
701
  assert_equal '', klass.comment.text
702
702
  end
703
703
 
704
+ def test_find_class_comment_define_class_under
705
+ content = <<-EOF
706
+ /*
707
+ * a comment for class Foo
708
+ */
709
+ VALUE foo = rb_define_class_under(rb_cObject, "Foo", rb_cObject);
710
+ EOF
711
+
712
+ klass = util_get_class content, 'foo'
713
+
714
+ assert_equal "a comment for class Foo", klass.comment.text
715
+ end
716
+
717
+ def test_find_class_comment_define_class_under_Init
718
+ content = <<-EOF
719
+ /*
720
+ * a comment for class Foo on Init
721
+ */
722
+ void
723
+ Init_Foo(void) {
724
+ /*
725
+ * a comment for class Foo on rb_define_class
726
+ */
727
+ VALUE foo = rb_define_class_under(rb_cObject, "Foo", rb_cObject);
728
+ }
729
+ EOF
730
+
731
+ klass = util_get_class content, 'foo'
732
+
733
+ # the inner comment is used since Object::Foo is not necessarily the same
734
+ # thing as "Foo" for Init_
735
+ assert_equal "a comment for class Foo on rb_define_class",
736
+ klass.comment.text
737
+ end
738
+
704
739
  def test_find_const_comment_rb_define
705
740
  content = <<-EOF
706
741
  /*
@@ -2253,6 +2253,41 @@ end
2253
2253
  assert_equal 'A nice girl', m.comment.text
2254
2254
  end
2255
2255
 
2256
+ def test_scan_constant_nodoc
2257
+ content = <<-CONTENT # newline is after M is important
2258
+ module M
2259
+
2260
+ C = v # :nodoc:
2261
+ end
2262
+ CONTENT
2263
+
2264
+ util_parser content
2265
+
2266
+ @parser.scan
2267
+
2268
+ c = @top_level.modules.first.constants.first
2269
+
2270
+ assert c.documented?
2271
+ end
2272
+
2273
+ def test_scan_constant_nodoc_block
2274
+ content = <<-CONTENT # newline is after M is important
2275
+ module M
2276
+
2277
+ C = v do # :nodoc:
2278
+ end
2279
+ end
2280
+ CONTENT
2281
+
2282
+ util_parser content
2283
+
2284
+ @parser.scan
2285
+
2286
+ c = @top_level.modules.first.constants.first
2287
+
2288
+ assert c.documented?
2289
+ end
2290
+
2256
2291
  def test_scan_meta_method_block
2257
2292
  content = <<-CONTENT
2258
2293
  class C
@@ -42,6 +42,32 @@ class TestRDocRDoc < RDoc::TestCase
42
42
  assert_equal [file], @rdoc.gather_files([file, file])
43
43
  end
44
44
 
45
+ def test_handle_pipe
46
+ $stdin = StringIO.new "hello"
47
+
48
+ out, = capture_io do
49
+ @rdoc.handle_pipe
50
+ end
51
+
52
+ assert_equal "\n<p>hello</p>\n", out
53
+ ensure
54
+ $stdin = STDIN
55
+ end
56
+
57
+ def test_handle_pipe_rd
58
+ $stdin = StringIO.new "=begin\nhello\n=end"
59
+
60
+ @rdoc.options.markup = 'rd'
61
+
62
+ out, = capture_io do
63
+ @rdoc.handle_pipe
64
+ end
65
+
66
+ assert_equal "\n<p>hello</p>\n", out
67
+ ensure
68
+ $stdin = STDIN
69
+ end
70
+
45
71
  def test_load_options
46
72
  temp_dir do
47
73
  options = RDoc::Options.new
@@ -613,11 +613,14 @@ Foo::Bar#bother
613
613
  def test_in_path_eh
614
614
  path = ENV['PATH']
615
615
 
616
- refute @driver.in_path?('/nonexistent')
616
+ temp_dir do |dir|
617
+ nonexistent = File.join dir, 'nonexistent'
618
+ refute @driver.in_path?(nonexistent)
617
619
 
618
- ENV['PATH'] = File.expand_path '..', __FILE__
620
+ ENV['PATH'] = File.expand_path '..', __FILE__
619
621
 
620
- assert @driver.in_path?(File.basename(__FILE__))
622
+ assert @driver.in_path?(File.basename(__FILE__))
623
+ end
621
624
  ensure
622
625
  ENV['PATH'] = path
623
626
  end
@@ -15,9 +15,12 @@ class TestRDocRIPaths < RDoc::TestCase
15
15
  end
16
16
 
17
17
  def test_class_path_nonexistent
18
- path = RDoc::RI::Paths.path true, true, true, true, '/nonexistent'
18
+ temp_dir do |dir|
19
+ nonexistent = File.join dir, 'nonexistent'
20
+ path = RDoc::RI::Paths.path true, true, true, true, nonexistent
19
21
 
20
- refute_includes path, '/nonexistent'
22
+ refute_includes path, nonexistent
23
+ end
21
24
  end
22
25
 
23
26
  def test_class_raw_path
@@ -30,7 +30,32 @@ class TestRDocRubyLex < RDoc::TestCase
30
30
  assert_equal expected, tokens
31
31
  end
32
32
 
33
- def test_class_tokenize_heredoc
33
+ def test_class_tokenize_def_heredoc
34
+ tokens = RDoc::RubyLex.tokenize <<-'RUBY', nil
35
+ def x
36
+ <<E
37
+ Line 1
38
+ Line 2
39
+ E
40
+ end
41
+ RUBY
42
+
43
+ expected = [
44
+ @TK::TkDEF .new( 0, 1, 0, 'def'),
45
+ @TK::TkSPACE .new( 3, 1, 3, ' '),
46
+ @TK::TkIDENTIFIER.new( 4, 1, 4, 'x'),
47
+ @TK::TkNL .new( 5, 1, 5, "\n"),
48
+ @TK::TkSPACE .new( 6, 2, 0, ' '),
49
+ @TK::TkSTRING .new( 8, 2, 2, %Q{"Line 1\nLine 2\n"}),
50
+ @TK::TkNL .new(27, 5, 28, "\n"),
51
+ @TK::TkEND .new(28, 6, 0, 'end'),
52
+ @TK::TkNL .new(31, 6, 28, "\n"),
53
+ ]
54
+
55
+ assert_equal expected, tokens
56
+ end
57
+
58
+ def test_class_tokenize_heredoc_indent
34
59
  tokens = RDoc::RubyLex.tokenize <<-'RUBY', nil
35
60
  string = <<-STRING
36
61
  Line 1
@@ -69,6 +94,28 @@ U
69
94
  assert_equal expected, tokens
70
95
  end
71
96
 
97
+ def test_class_tokenize_percent_w
98
+ tokens = RDoc::RubyLex.tokenize '%w[hi]', nil
99
+
100
+ expected = [
101
+ @TK::TkDSTRING.new( 0, 1, 0, '%w[hi]'),
102
+ @TK::TkNL .new( 6, 1, 6, "\n"),
103
+ ]
104
+
105
+ assert_equal expected, tokens
106
+ end
107
+
108
+ def test_class_tokenize_string
109
+ tokens = RDoc::RubyLex.tokenize "'hi'", nil
110
+
111
+ expected = [
112
+ @TK::TkSTRING.new( 0, 1, 0, "'hi'"),
113
+ @TK::TkNL .new( 4, 1, 4, "\n"),
114
+ ]
115
+
116
+ assert_equal expected, tokens
117
+ end
118
+
72
119
  def test_unary_minus
73
120
  ruby_lex = RDoc::RubyLex.new("-1", nil)
74
121
  assert_equal("-1", ruby_lex.token.value)
metadata CHANGED
@@ -1,12 +1,12 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: rdoc
3
3
  version: !ruby/object:Gem::Version
4
- hash: 17
4
+ hash: 31
5
5
  prerelease:
6
6
  segments:
7
7
  - 3
8
- - 11
9
- version: "3.11"
8
+ - 12
9
+ version: "3.12"
10
10
  platform: ruby
11
11
  authors:
12
12
  - Eric Hodel
@@ -38,7 +38,7 @@ cert_chain:
38
38
  x52qPcexcYZR7w==
39
39
  -----END CERTIFICATE-----
40
40
 
41
- date: 2011-10-17 00:00:00 Z
41
+ date: 2011-12-15 00:00:00 Z
42
42
  dependencies:
43
43
  - !ruby/object:Gem::Dependency
44
44
  name: json
@@ -146,6 +146,7 @@ extensions: []
146
146
 
147
147
  extra_rdoc_files:
148
148
  - Manifest.txt
149
+ - DEVELOPERS.rdoc
149
150
  - History.rdoc
150
151
  - LICENSE.rdoc
151
152
  - LEGAL.rdoc
@@ -156,6 +157,7 @@ extra_rdoc_files:
156
157
  files:
157
158
  - .autotest
158
159
  - .document
160
+ - DEVELOPERS.rdoc
159
161
  - History.rdoc
160
162
  - LEGAL.rdoc
161
163
  - LICENSE.rdoc
@@ -422,7 +424,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
422
424
  requirements: []
423
425
 
424
426
  rubyforge_project: rdoc
425
- rubygems_version: 1.8.10
427
+ rubygems_version: 1.8.12
426
428
  signing_key:
427
429
  specification_version: 3
428
430
  summary: RDoc produces HTML and command-line documentation for Ruby projects
metadata.gz.sig CHANGED
Binary file