Infer title and heading from comment

p8 · p8 · commit 2293c871f221 · 2023-05-19T21:39:02.000+02:00
If the comment of the class/module doesn't have a `h1` defined 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.
diff --git a/lib/rdoc/generator/template/rails/_context.rhtml b/lib/rdoc/generator/template/rails/_context.rhtml
@@ -1,4 +1,7 @@
 <div id="content">
+  <% unless context.comment_title %>
+    <h1><%= context.title %></h1>
+  <% end %>
   <% unless (description = context.description).empty? %>
     <div class="description">
       <%= description %>
diff --git a/lib/rdoc/generator/template/rails/class.rhtml b/lib/rdoc/generator/template/rails/class.rhtml
@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
-    <title><%= h klass.full_name %></title>
+    <title><%= h @options.title %> | <%= h klass.title %></title>
     <meta charset="<%= @options.charset %>" />
     <meta name="viewport" content="width=device-width,initial-scale=1">
     <%= include_template '_head.rhtml', {:context => klass, :rel_prefix => rel_prefix, :tree_keys => klass.full_name.split('::') } %>
diff --git a/lib/sdoc/generator.rb b/lib/sdoc/generator.rb
@@ -20,6 +20,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
 
diff --git a/spec/rdoc_generator_markup_spec.rb b/spec/rdoc_generator_markup_spec.rb
@@ -0,0 +1,31 @@
+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 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
