rdoc 3.5.1 → 3.5.2

data/lib/rdoc/generator/template/darkfish/rdoc.css

@@ -278,46 +278,46 @@ ul.link-list .type {
 
 
 /* @group Documentation Section */
-#description {
+.description {
   font-size: 100%;
   color: #333;
 }
 
-#description p {
+.description p {
   margin: 1em 0.4em;
 }
 
-#description li p {
+.description li p {
   margin: 0;
 }
 
-#description ul {
+.description ul {
   margin-left: 1.5em;
 }
-#description ul li {
+.description ul li {
   line-height: 1.4em;
 }
 
-#description dl,
+.description dl,
 #documentation dl {
   margin: 8px 1.5em;
   border: 1px solid #ccc;
 }
-#description dl {
+.description dl {
   font-size: 14px;
 }
 
-#description dt,
+.description dt,
 #documentation dt {
   padding: 2px 4px;
   font-weight: bold;
   background: #ddd;
 }
-#description dd,
+.description dd,
 #documentation dd  {
   padding: 2px 12px;
 }
-#description dd + dt,
+.description dd + dt,
 #documentation dd + dt {
   margin-top: 0.7em;
 }
@@ -325,9 +325,21 @@ ul.link-list .type {
 #documentation .section {
   font-size: 90%;
 }
-#documentation h3.section-header {
+
+#documentation h2.section-header {
   margin-top: 2em;
   padding: 0.75em 0.5em;
+  background: #ccc;
+  color: #333;
+  font-size: 175%;
+  border: 1px solid #bbb;
+  -moz-border-radius: 3px;
+  -webkit-border-radius: 3px;
+}
+
+#documentation h3.section-header {
+  margin-top: 2em;
+  padding: 0.25em 0.5em;
   background-color: #dedede;
   color: #333;
   font-size: 150%;
@@ -359,6 +371,23 @@ ul.link-list .type {
   color: #666;
 }
 
+.documentation-section h2 {
+  position: relative;
+}
+
+.documentation-section h2 a {
+  position: absolute;
+  top: 8px;
+  right: 10px;
+  font-size: 12px;
+  color: #9b9877;
+  visibility: hidden;
+}
+
+.documentation-section h2:hover a {
+  visibility: visible;
+}
+
 /* @group Method Details */
 
 #documentation .method-source-code {

data/lib/rdoc/markup.rb

@@ -502,10 +502,11 @@ require 'rdoc'
 #   Starts a new section in the output.  The title following +:section:+ is
 #   used as the section heading, and the remainder of the comment containing
 #   the section is used as introductory text.  Subsequent methods, aliases,
-#   attributes, and classes will be documented in this section.  A :section:
-#   comment block may have one or more lines before the :section: directive.
-#   These will be removed, and any identical lines at the end of the block are
-#   also removed.  This allows you to add visual cues such as:
+#   attributes, and classes will be documented in this section.
+#
+#   A :section: comment block may have one or more lines before the :section:
+#   directive.  These will be removed, and any identical lines at the end of
+#   the block are also removed.  This allows you to add visual cues such as:
 #
 #     # ----------------------------------------
 #     # :section: My Section
@@ -513,7 +514,10 @@ require 'rdoc'
 #     # See it glisten in the noon-day sun.
 #     # ----------------------------------------
 #
-#   <i>Note: Current formatters to not take sections into account.</i>
+#   Sections may be referenced multiple times in a class or module allowing
+#   methods, attributes and constants to be ordered one way for implementation
+#   ordering but still grouped together in documentation.  If a section has
+#   multiple comments they will be concatenated with a dividing rule.
 #
 # [+:call-seq:+]
 #   Lines up to the next blank line in the comment are treated as the method's

data/lib/rdoc/markup/to_html.rb

@@ -10,6 +10,8 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
 
   include RDoc::Text
 
+  # :section: Utilities
+
   ##
   # Maps RDoc::Markup::Parser::LIST_TOKENS types to HTML tags
 
@@ -55,6 +57,8 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     File.join(*from)
   end
 
+  # :section:
+
   ##
   # Creates a new formatter that will output HTML
 
@@ -75,54 +79,21 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     init_tags
   end
 
-  ##
-  # Maps attributes to HTML tags
-
-  def init_tags
-    add_tag :BOLD, "<b>",  "</b>"
-    add_tag :TT,   "<tt>", "</tt>"
-    add_tag :EM,   "<em>", "</em>"
-  end
+  # :section: Special Handling
+  #
+  # These methods handle special markup added by RDoc::Markup#add_special.
 
   ##
-  # Generate a hyperlink for +url+, labeled with +text+.  Handles the special
-  # cases for img: and link: described under handle_special_HYPERLINK
-
-  def gen_url(url, text)
-    if url =~ /([A-Za-z]+):(.*)/ then
-      type = $1
-      path = $2
-    else
-      type = "http"
-      path = url
-      url  = "http://#{url}"
-    end
-
-    if type == "link" then
-      url = if path[0, 1] == '#' then # is this meaningful?
-              path
-            else
-              self.class.gen_relative_url @from_path, path
-            end
-    end
-
-    if (type == "http" or type == "link") and
-       url =~ /\.(gif|png|jpg|jpeg|bmp)$/ then
-      "<img src=\"#{url}\" />"
-    else
-      "<a href=\"#{url}\">#{text.sub(%r{^#{type}:/*}, '')}</a>"
-    end
-  end
-
-  # :section: Special handling
-
-  ##
-  # And we're invoked with a potential external hyperlink. <tt>mailto:</tt>
-  # just gets inserted. <tt>http:</tt> links are checked to see if they
-  # reference an image. If so, that image gets inserted using an
-  # <tt><img></tt> tag. Otherwise a conventional <tt><a href></tt> is used.
-  # We also support a special type of hyperlink, <tt>link:</tt>, which is a
-  # reference to a local file whose path is relative to the --op directory.
+  # +special+ is a potential hyperlink.  The following schemes are handled:
+  #
+  # <tt>mailto:</tt>::
+  #   Inserted as-is.
+  # <tt>http:</tt>::
+  #   Links are checked to see if they reference an image. If so, that image
+  #   gets inserted using an <tt><img></tt> tag. Otherwise a conventional
+  #   <tt><a href></tt> is used.
+  # <tt>link:</tt>::
+  #   Reference to a local file relative to the output directory.
 
   def handle_special_HYPERLINK(special)
     url = special.text
@@ -130,8 +101,8 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   end
 
   ##
-  # Here's a hyperlink where the label is different to the URL
-  # <label>[url] or {long label}[url]
+  # This +special+ is a hyperlink where the label is different from the URL
+  # label[url] or {long label}[url]
 
   def handle_special_TIDYLINK(special)
     text = special.text
@@ -143,41 +114,9 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     gen_url url, label
   end
 
-  # :section: Utilities
-
-  ##
-  # Wraps +txt+ to +line_len+
-
-  def wrap(txt, line_len = 76)
-    res = []
-    sp = 0
-    ep = txt.length
-
-    while sp < ep
-      # scan back for a space
-      p = sp + line_len - 1
-      if p >= ep
-        p = ep
-      else
-        while p > sp and txt[p] != ?\s
-          p -= 1
-        end
-        if p <= sp
-          p = sp + line_len
-          while p < ep and txt[p] != ?\s
-            p += 1
-          end
-        end
-      end
-      res << txt[sp...p] << "\n"
-      sp = p
-      sp += 1 while sp < ep and txt[sp] == ?\s
-    end
-
-    res.join.strip
-  end
-
   # :section: Visitor
+  #
+  # These methods implement the HTML visitor.
 
   ##
   # Prepares the visitor for HTML generation
@@ -283,6 +222,8 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     @res << raw.parts.join("\n")
   end
 
+  # :section: Utilities
+
   ##
   # CGI escapes +text+
 
@@ -290,6 +231,36 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     CGI.escapeHTML text
   end
 
+  ##
+  # Generate a hyperlink for +url+, labeled with +text+.  Handles the special
+  # cases for img: and link: described under handle_special_HYPERLINK
+
+  def gen_url(url, text)
+    if url =~ /([A-Za-z]+):(.*)/ then
+      type = $1
+      path = $2
+    else
+      type = "http"
+      path = url
+      url  = "http://#{url}"
+    end
+
+    if type == "link" then
+      url = if path[0, 1] == '#' then # is this meaningful?
+              path
+            else
+              self.class.gen_relative_url @from_path, path
+            end
+    end
+
+    if (type == "http" or type == "link") and
+       url =~ /\.(gif|png|jpg|jpeg|bmp)$/ then
+      "<img src=\"#{url}\" />"
+    else
+      "<a href=\"#{url}\">#{text.sub(%r{^#{type}:/*}, '')}</a>"
+    end
+  end
+
   ##
   # Determines the HTML list element for +list_type+ and +open_tag+
 
@@ -299,6 +270,15 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     tags[open_tag ? 0 : 1]
   end
 
+  ##
+  # Maps attributes to HTML tags
+
+  def init_tags
+    add_tag :BOLD, "<b>",  "</b>"
+    add_tag :TT,   "<tt>", "</tt>"
+    add_tag :EM,   "<em>", "</em>"
+  end
+
   ##
   # Returns the HTML tag for +list_type+, possible using a label from
   # +list_item+

data/lib/rdoc/options.rb

@@ -747,7 +747,7 @@ Usage: #{opt.program_name} [options] [names...]
 
     if @generator.respond_to? :setup_options then
       @option_parser ||= OptionParser.new
-      @generator.setup_options self 
+      @generator.setup_options self
     end
   end
 

data/lib/rdoc/text.rb

@@ -260,5 +260,37 @@ http://rubyforge.org/tracker/?atid=2472&group_id=627&func=browse
     html
   end
 
+  ##
+  # Wraps +txt+ to +line_len+
+
+  def wrap(txt, line_len = 76)
+    res = []
+    sp = 0
+    ep = txt.length
+
+    while sp < ep
+      # scan back for a space
+      p = sp + line_len - 1
+      if p >= ep
+        p = ep
+      else
+        while p > sp and txt[p] != ?\s
+          p -= 1
+        end
+        if p <= sp
+          p = sp + line_len
+          while p < ep and txt[p] != ?\s
+            p += 1
+          end
+        end
+      end
+      res << txt[sp...p] << "\n"
+      sp = p
+      sp += 1 while sp < ep and txt[sp] == ?\s
+    end
+
+    res.join.strip
+  end
+
 end
 

data/test/test_rdoc_any_method.rb

@@ -47,7 +47,7 @@ method(a, b) { |c, d| ... }
   def test_markup_code
     tokens = [
       RDoc::RubyToken::TkCONSTANT. new(0, 0, 0, 'CONSTANT'),
-      RDoc::RubyToken::TkKW.       new(0, 0, 0, 'KW'),
+      RDoc::RubyToken::TkDEF.       new(0, 0, 0, 'KW'),
       RDoc::RubyToken::TkIVAR.     new(0, 0, 0, 'IVAR'),
       RDoc::RubyToken::TkOp.       new(0, 0, 0, 'Op'),
       RDoc::RubyToken::TkId.       new(0, 0, 0, 'Id'),
@@ -90,6 +90,12 @@ method(a, b) { |c, d| ... }
     assert_equal 'C1',    instance_method.parent_name
     assert_equal '(foo)', instance_method.params
 
+    aliased_method = Marshal.load Marshal.dump(@c2.method_list.last)
+
+    assert_equal 'C2#a',  aliased_method.full_name
+    assert_equal 'C2',    aliased_method.parent_name
+    assert_equal '()',    aliased_method.params
+
     class_method = Marshal.load Marshal.dump(@c1.method_list.first)
 
     assert_equal 'C1::m', class_method.full_name

data/test/test_rdoc_context.rb

@@ -251,6 +251,34 @@ class TestRDocContext < XrefTestCase
     refute_equal @c2_c3, @c3
   end
 
+  def test_each_section
+    sects  = []
+    consts = []
+    attrs  = []
+
+    @c1.each_section do |section, constants, attributes|
+      sects  << section
+      consts << constants
+      attrs  << attributes
+    end
+
+    assert_equal [nil, 'separate'], sects.map { |section| section.title }
+
+    expected_consts = [
+      [@c1.constants.first],
+      [],
+    ]
+
+    assert_equal expected_consts, consts
+
+    expected_attrs = [
+      [@c1.attributes[0], @c1.attributes[3]],
+      [@c1.attributes[1], @c1.attributes[2]],
+    ]
+
+    assert_equal expected_attrs, attrs
+  end
+
   def test_find_attribute_named
     assert_equal nil,  @c1.find_attribute_named('none')
     assert_equal 'R',  @c1.find_attribute_named('attr').rw
@@ -373,5 +401,42 @@ class TestRDocContext < XrefTestCase
     assert_equal(-1, @c2_c3.<=>(@c3))
   end
 
+  def test_methods_by_type
+    expected = {
+      'instance' => {
+        :private   => [],
+        :protected => [],
+        :public    => [@c1_m],
+      },
+      'class' => {
+        :private   => [],
+        :protected => [],
+        :public    => [@c1__m],
+      },
+    }
+
+    assert_equal expected, @c1.methods_by_type
+  end
+
+  def test_methods_by_type_section
+    separate = @c1.sections_hash['separate']
+    @c1_m.section = separate
+
+    expected = {
+      'instance' => {
+        :private   => [],
+        :protected => [],
+        :public    => [@c1_m],
+      },
+      'class' => {
+        :private   => [],
+        :protected => [],
+        :public    => [],
+      },
+    }
+
+    assert_equal expected, @c1.methods_by_type(separate)
+  end
+
 end