From 60e05b54004ebc34244888b840ae344815238700 Mon Sep 17 00:00:00 2001
From: Petrik <petrik@deheus.net>
Date: Fri, 19 May 2023 21:30:25 +0200
Subject: [PATCH] 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.
---
 .../generator/template/rails/_context.rhtml   |  3 ++
 lib/sdoc/generator.rb                         | 10 ++++++
 spec/rdoc_generator_markup_spec.rb            | 36 +++++++++++++++++++
 3 files changed, 49 insertions(+)
 create mode 100644 spec/rdoc_generator_markup_spec.rb

diff --git a/lib/rdoc/generator/template/rails/_context.rhtml b/lib/rdoc/generator/template/rails/_context.rhtml
index 748ba2c5..13f868ec 100644
--- 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/sdoc/generator.rb b/lib/sdoc/generator.rb
index 930bf687..ec4957fe 100644
--- a/lib/sdoc/generator.rb
+++ b/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
 
diff --git a/spec/rdoc_generator_markup_spec.rb b/spec/rdoc_generator_markup_spec.rb
new file mode 100644
index 00000000..2b2a2eb0
--- /dev/null
+++ 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