Infer title and heading from comment

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