Infer title and heading from comment

Some classes in Rails have a h1 heading defined in the RDoc comment.
For example:
  https://github.com/rails/rails/blob/4e1fe73028f4b01c8e5179989511b21925f70b20/activesupport/lib/active_support/current_attributes.rb#L8
  https://github.com/rails/rails/blob/4e1fe73028f4b01c8e5179989511b21925f70b20/actionpack/lib/action_controller/metal/strong_parameters.rb#L1159
This makes the heading more readable especially when there are a lot of
namespaces.

For SEO it helps if all classes have a h1 heading, but having to add
them by hand is cumbersome when we can generate them instead.

By looking at the comment of the class/module we can see if it has a
`h1` heading when it's starting with `= ` or `# `. If the heading is
missing we can generate a heading with the full name of the class
instead. This will prevent us from having to add the h1 for each class
in Rails.

This also adds the `@options.title` to the `title` tag of every class.

Author: p8

lib/rdoc/generator/template/rails/_context.rhtml

@@ -1,5 +1,8 @@
 <div id="content">
   <% unless (description = context.description).empty? %>
+    <% unless context.comment_title %>
+      <h1><%= context.title %></h1>
+    <% end %>
     <div class="description">
       <%= description %>
     </div>

lib/sdoc/generator.rb

@@ -19,6 +19,16 @@ class RDoc::Options
   attr_accessor :search_index
 end
 
+module RDoc::Generator::Markup
+  def comment_title
+    @comment_title ||= @comment.to_s.match(/\A[=#] (.*)$/) {|match| match[1] }
+  end
+
+  def title
+    comment_title || full_name
+  end
+end
+
 class RDoc::Generator::SDoc
   RDoc::RDoc.add_generator self
 

spec/rdoc_generator_markup_spec.rb

@@ -0,0 +1,36 @@
+require File.join(File.dirname(__FILE__), '/spec_helper')
+
+describe RDoc::Generator::Markup do
+  before :each do
+    @module = RDoc::NormalModule.new 'Example::SomeClass'
+  end
+
+  describe "#comment_title" do
+    it "should parse the h1 title from the comment if present" do
+      @module.comment = RDoc::Comment.new '= Some Title'
+      _(@module.comment_title).must_equal 'Some Title'
+    end
+
+    it "should parse the markdown h1 title from the comment if present" do
+      @module.comment = RDoc::Comment.new '# Markdown Title'
+      _(@module.comment_title).must_equal 'Markdown Title'
+    end
+
+    it "should ignore lower level titles" do
+      @module.comment = RDoc::Comment.new '== Some Title'
+      _(@module.comment_title).must_equal nil
+    end
+  end
+
+  describe "#title" do
+    it "should parse the h1 title from the comment if present" do
+      @module.comment = RDoc::Comment.new '= Some Title'
+      _(@module.title).must_equal 'Some Title'
+    end
+
+    it "should fallback to the full_name" do
+      @module.comment = RDoc::Comment.new 'Some comment without title'
+      _(@module.title).must_equal "Example::SomeClass"
+    end
+  end
+end