Infer title and heading from comment

p8 · p8 · commit dce7139e1c34 · 2023-05-19T21:52:47.000+02:00
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.
diff --git a/lib/rdoc/generator/template/rails/_context.rhtml b/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>
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,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
