Merge pull request #355 from jonathanhefner/description_for

Skip rendering empty descriptions

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

@@ -11,7 +11,7 @@
     <h2 class="content__divider">Required Files</h2>
     <ul>
       <% @context.requires.each do |req| %>
-        <li><%= full_name req.name %></li>
+        <li><%= full_name_for req.name %></li>
       <% end %>
     </ul>
   <% end %>
@@ -24,7 +24,7 @@
       <% ancestors.each do |kind, ancestor| %>
         <li>
           <span class="kind"><%= kind %></span>
-          <%= ancestor.is_a?(String) ? full_name(ancestor) : link_to(ancestor) %>
+          <%= ancestor.is_a?(String) ? full_name_for(ancestor) : link_to(ancestor) %>
         </li>
       <% end %>
     </ul>
@@ -52,23 +52,19 @@
       </div>
     <% end %>
 
-    <% if section.comment then %>
-      <div class="description">
-        <%= section.description %>
-      </div>
-    <% end %>
+    <%= description_for section %>
 
     <% unless constants.empty? %>
       <!-- Section constants -->
       <h2 class="content__divider">Constants</h2>
       <table border='0' cellpadding='5'>
         <% constants.each do |const| %>
           <tr valign='top'>
-            <td class="attr-name"><%= short_name const %></td>
+            <td class="attr-name"><%= short_name_for const %></td>
             <td>=</td>
             <td class="attr-value"><%= h const.value %></td>
           </tr>
-          <% if const.comment %>
+          <% if const.comment && !const.comment.empty? %>
             <tr valign='top'>
               <td>&nbsp;</td>
               <td colspan="2" class="attr-desc"><%= const.description.strip %></td>
@@ -88,7 +84,7 @@
             <td class='attr-rw'>
               [<%= attrib.rw %>]
             </td>
-            <td class='attr-name'><%= short_name attrib %></td>
+            <td class='attr-name'><%= short_name_for attrib %></td>
             <td class='attr-desc'><%= attrib.description.strip %></td>
           </tr>
         <% end %>
@@ -116,22 +112,18 @@
             <p class="method__aka">
               Also aliased as:
               <%# Sometimes a parent cannot be determined. See ruby/rdoc@85ebfe13dc. %>
-              <%= method.aliases.map { |aka| link_to_if aka.parent, short_name(aka), aka }.join(", ") %>.
+              <%= method.aliases.map { |aka| link_to_if aka.parent, short_name_for(aka), aka }.join(", ") %>.
             </p>
           <% end %>
 
           <% if alias_for = method.is_alias_for then %>
             <p class="method__aka">
               Alias for:
-              <%= link_to short_name(alias_for), alias_for %>.
+              <%= link_to short_name_for(alias_for), alias_for %>.
             </p>
           <% end %>
 
-          <% if method.comment %>
-            <div class="description">
-              <%= method.description %>
-            </div>
-          <% end %>
+          <%= description_for method %>
 
           <% source_code, source_url = method_source_code_and_url(method) %>
           <% if source_code %>

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

@@ -1,7 +1,7 @@
 <% unless @context.classes_and_modules.empty? %>
-  <a href="#namespace" class="namespace-link"><%= short_name(@context) %> namespace</a>
+  <a href="#namespace" class="namespace-link"><%= short_name_for(@context) %> namespace</a>
 <% end %>
-<%= button_to_search @context, display_name: short_name(@context) %>
+<%= button_to_search @context, display_name: short_name_for(@context) %>
 
 <% if outline = outline(@context) %>
   <div class="nav__heading">Outline</div>
@@ -14,7 +14,7 @@
   <div class="nav__heading">Methods</div>
   <ul class="nav__list">
     <% methods.each do |rdoc_method| %>
-      <li><%= link_to short_name(rdoc_method), rdoc_method,
+      <li><%= link_to short_name_for(rdoc_method), rdoc_method,
                 class: "ref-link nav__method-link#{"--singleton" if rdoc_method.singleton}" %></li>
     <% end %>
   </ul>

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

@@ -18,7 +18,7 @@
     <main id="content" class="content">
         <div class="content__title">
           <%= "<h1>" if @context.comment.empty? %>
-            <%= full_name @context %>
+            <%= full_name_for @context %>
           <%= "</h1>" if @context.comment.empty? %>
         </div>
 

lib/sdoc/helpers.rb

@@ -28,7 +28,7 @@ def link_to(text, url = nil, html_attributes = {})
   end
 
   def _link_body(text)
-    text.is_a?(RDoc::CodeObject) ? full_name(text) : text
+    text.is_a?(RDoc::CodeObject) ? full_name_for(text) : text
   end
 
   def link_to_if(condition, text, *args)
@@ -43,21 +43,27 @@ def link_to_external(text, url, html_attributes = {})
     link_to(text, url, html_attributes)
   end
 
-  def button_to_search(query, display_name: full_name(query))
+  def button_to_search(query, display_name: full_name_for(query))
     query = query.full_name if query.is_a?(RDoc::CodeObject)
     %(<button class="query-button" data-query="#{h query} ">Search #{display_name}</button>)
   end
 
-  def full_name(named)
+  def full_name_for(named)
     named = named.full_name if named.is_a?(RDoc::CodeObject)
     "<code>#{named.split(%r"(?<=./|.::)").map { |part| h part }.join("<wbr>")}</code>"
   end
 
-  def short_name(named)
+  def short_name_for(named)
     named = named.name if named.is_a?(RDoc::CodeObject)
     "<code>#{h named}</code>"
   end
 
+  def description_for(rdoc_object)
+    if rdoc_object.comment && !rdoc_object.comment.empty?
+      %(<div class="description">#{rdoc_object.description}</div>)
+    end
+  end
+
   def base_tag_for_context(context)
     relative_root = "../" * context.path.count("/")
     %(<base href="./#{relative_root}" data-current-path="#{context.path}">)

spec/helpers_spec.rb

@@ -119,7 +119,7 @@
         must_equal %(<a href="foo/bar/qux.html" data-hoge="fuga">foo/bar/qux.html</a>)
     end
 
-    it "uses #full_name when the text argument is an RDoc::CodeObject" do
+    it "uses #full_name_for when the text argument is an RDoc::CodeObject" do
       top_level = rdoc_top_level_for <<~RUBY
         module Foo; class Bar; def qux; end; end; end
       RUBY
@@ -131,7 +131,7 @@ module Foo; class Bar; def qux; end; end; end
         top_level.find_module_named("Foo::Bar").find_method("qux", false),
       ].each do |code_object|
         _(@helpers.link_to(code_object, "url")).
-          must_equal %(<a href="url">#{@helpers.full_name(code_object)}</a>)
+          must_equal %(<a href="url">#{@helpers.full_name_for(code_object)}</a>)
       end
     end
 
@@ -157,7 +157,7 @@ module Foo; module Bar; end
       RUBY
 
       _(@helpers.link_to(rdoc_module)).
-        must_equal %(<a href="/#{rdoc_module.path}" class="ref-link">#{@helpers.full_name(rdoc_module)}</a>)
+        must_equal %(<a href="/#{rdoc_module.path}" class="ref-link">#{@helpers.full_name_for(rdoc_module)}</a>)
 
       _(@helpers.link_to("<code>Bar</code>", rdoc_module)).
         must_equal %(<a href="/#{rdoc_module.path}" class="ref-link"><code>Bar</code></a>)
@@ -183,7 +183,7 @@ module Foo; module Bar; end
         module Foo; class Bar; end; end
       RUBY
 
-      _(@helpers.link_to_if(false, rdoc_module, "url")).must_equal @helpers.full_name(rdoc_module)
+      _(@helpers.link_to_if(false, rdoc_module, "url")).must_equal @helpers.full_name_for(rdoc_module)
     end
   end
 
@@ -233,49 +233,69 @@ module Foo; def <<(*); end; end
     end
   end
 
-  describe "#full_name" do
+  describe "#full_name_for" do
     it "wraps name in <code>" do
-      _(@helpers.full_name("Foo")).must_equal "<code>Foo</code>"
+      _(@helpers.full_name_for("Foo")).must_equal "<code>Foo</code>"
     end
 
     it "inserts word-break opportunities into module names" do
-      _(@helpers.full_name("Foo::Bar::Qux")).must_equal "<code>Foo::<wbr>Bar::<wbr>Qux</code>"
-      _(@helpers.full_name("::Foo::Bar::Qux")).must_equal "<code>::Foo::<wbr>Bar::<wbr>Qux</code>"
+      _(@helpers.full_name_for("Foo::Bar::Qux")).must_equal "<code>Foo::<wbr>Bar::<wbr>Qux</code>"
+      _(@helpers.full_name_for("::Foo::Bar::Qux")).must_equal "<code>::Foo::<wbr>Bar::<wbr>Qux</code>"
     end
 
     it "inserts word-break opportunities into file paths" do
-      _(@helpers.full_name("path/to/file.rb")).must_equal "<code>path/<wbr>to/<wbr>file.rb</code>"
-      _(@helpers.full_name("/path/to/file.rb")).must_equal "<code>/path/<wbr>to/<wbr>file.rb</code>"
+      _(@helpers.full_name_for("path/to/file.rb")).must_equal "<code>path/<wbr>to/<wbr>file.rb</code>"
+      _(@helpers.full_name_for("/path/to/file.rb")).must_equal "<code>/path/<wbr>to/<wbr>file.rb</code>"
     end
 
     it "escapes name parts" do
-      _(@helpers.full_name("ruby&rails/file.rb")).must_equal "<code>ruby&amp;rails/<wbr>file.rb</code>"
+      _(@helpers.full_name_for("ruby&rails/file.rb")).must_equal "<code>ruby&amp;rails/<wbr>file.rb</code>"
     end
 
     it "uses RDoc::CodeObject#full_name when argument is an RDoc::CodeObject" do
       rdoc_module = rdoc_top_level_for(<<~RUBY).find_module_named("Foo::Bar::Qux")
         module Foo; module Bar; class Qux; end; end; end
       RUBY
 
-      _(@helpers.full_name(rdoc_module)).must_equal "<code>Foo::<wbr>Bar::<wbr>Qux</code>"
+      _(@helpers.full_name_for(rdoc_module)).must_equal "<code>Foo::<wbr>Bar::<wbr>Qux</code>"
     end
   end
 
-  describe "#short_name" do
+  describe "#short_name_for" do
     it "wraps name in <code>" do
-      _(@helpers.short_name("foo")).must_equal "<code>foo</code>"
+      _(@helpers.short_name_for("foo")).must_equal "<code>foo</code>"
     end
 
     it "escapes the name" do
-      _(@helpers.short_name("<=>")).must_equal "<code>&lt;=&gt;</code>"
+      _(@helpers.short_name_for("<=>")).must_equal "<code>&lt;=&gt;</code>"
     end
 
     it "uses RDoc::CodeObject#name when argument is an RDoc::CodeObject" do
       rdoc_method = rdoc_top_level_for(<<~RUBY).find_module_named("Foo").find_method("bar", false)
         module Foo; def bar; end; end
       RUBY
 
-      _(@helpers.short_name(rdoc_method)).must_equal "<code>bar</code>"
+      _(@helpers.short_name_for(rdoc_method)).must_equal "<code>bar</code>"
+    end
+  end
+
+  describe "#description_for" do
+    it "returns RDoc::CodeObject#description wrapped in div.description" do
+      rdoc_module = rdoc_top_level_for(<<~RUBY).find_module_named("Foo")
+        # This is +Foo+.
+        module Foo; end
+      RUBY
+
+      _(@helpers.description_for(rdoc_module)).
+        must_equal %(<div class="description">\n<p>This is <code>Foo</code>.</p>\n</div>)
+    end
+
+    it "returns nil when RDoc::CodeObject#description is empty" do
+      rdoc_module = rdoc_top_level_for(<<~RUBY).find_module_named("Foo")
+        module Foo; end
+      RUBY
+
+      _(@helpers.description_for(rdoc_module)).must_be_nil
     end
   end