From 33099fa9f1898cc4f7841a1a87b53ba75e54e478 Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Thu, 28 Dec 2023 12:31:25 -0600 Subject: [PATCH] Skip rendering empty descriptions `RDoc::CodeObject#comment` appears to always return a string, even if no comment has been specified. Thus the truthiness of `comment` cannot be used to skip rendering empty descriptions. This commit adds a `description_for` helper to encapsulate properly checking `comment` and wrapping the rendered description in a `div`. This commit also renames the `full_name` and `short_name` helpers to `full_name_for` and `short_name_for` to match `description_for`. --- .../generator/template/rails/_context.rhtml | 26 ++++------ .../template/rails/_module_nav.rhtml | 6 +-- lib/rdoc/generator/template/rails/file.rhtml | 2 +- lib/sdoc/helpers.rb | 14 +++-- spec/helpers_spec.rb | 52 +++++++++++++------ 5 files changed, 59 insertions(+), 41 deletions(-) diff --git a/lib/rdoc/generator/template/rails/_context.rhtml b/lib/rdoc/generator/template/rails/_context.rhtml index 566d91e7..c1dd1378 100644 --- a/lib/rdoc/generator/template/rails/_context.rhtml +++ b/lib/rdoc/generator/template/rails/_context.rhtml @@ -11,7 +11,7 @@

Required Files

<% end %> @@ -24,7 +24,7 @@ <% ancestors.each do |kind, ancestor| %>
  • <%= kind %> - <%= ancestor.is_a?(String) ? full_name(ancestor) : link_to(ancestor) %> + <%= ancestor.is_a?(String) ? full_name_for(ancestor) : link_to(ancestor) %>
    • <% end %> @@ -52,11 +52,7 @@ <% end %> - <% if section.comment then %> -
    - <%= section.description %> -
    - <% end %> + <%= description_for section %> <% unless constants.empty? %> @@ -64,11 +60,11 @@ <% constants.each do |const| %> - + - <% if const.comment %> + <% if const.comment && !const.comment.empty? %> @@ -88,7 +84,7 @@ - + <% end %> @@ -116,22 +112,18 @@

    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(", ") %>.

    <% end %> <% if alias_for = method.is_alias_for then %>

    Alias for: - <%= link_to short_name(alias_for), alias_for %>. + <%= link_to short_name_for(alias_for), alias_for %>.

    <% end %> - <% if method.comment %> -
    - <%= method.description %> -
    - <% end %> + <%= description_for method %> <% source_code, source_url = method_source_code_and_url(method) %> <% if source_code %> diff --git a/lib/rdoc/generator/template/rails/_module_nav.rhtml b/lib/rdoc/generator/template/rails/_module_nav.rhtml index 07710d25..df6b063d 100644 --- a/lib/rdoc/generator/template/rails/_module_nav.rhtml +++ b/lib/rdoc/generator/template/rails/_module_nav.rhtml @@ -1,7 +1,7 @@ <% unless @context.classes_and_modules.empty? %> - <%= short_name(@context) %> namespace + <%= short_name_for(@context) %> namespace <% end %> -<%= button_to_search @context, display_name: short_name(@context) %> +<%= button_to_search @context, display_name: short_name_for(@context) %> <% if outline = outline(@context) %>
    Outline
    @@ -14,7 +14,7 @@
    Methods
    diff --git a/lib/rdoc/generator/template/rails/file.rhtml b/lib/rdoc/generator/template/rails/file.rhtml index c930b353..0be5ea15 100644 --- a/lib/rdoc/generator/template/rails/file.rhtml +++ b/lib/rdoc/generator/template/rails/file.rhtml @@ -18,7 +18,7 @@
    <%= "

    " if @context.comment.empty? %> - <%= full_name @context %> + <%= full_name_for @context %> <%= "

    " if @context.comment.empty? %>
    diff --git a/lib/sdoc/helpers.rb b/lib/sdoc/helpers.rb index 54bdd35d..d608f112 100644 --- a/lib/sdoc/helpers.rb +++ b/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) %() end - def full_name(named) + def full_name_for(named) named = named.full_name if named.is_a?(RDoc::CodeObject) "#{named.split(%r"(?<=./|.::)").map { |part| h part }.join("")}" end - def short_name(named) + def short_name_for(named) named = named.name if named.is_a?(RDoc::CodeObject) "#{h named}" end + def description_for(rdoc_object) + if rdoc_object.comment && !rdoc_object.comment.empty? + %(
    #{rdoc_object.description}
    ) + end + end + def base_tag_for_context(context) relative_root = "../" * context.path.count("/") %() diff --git a/spec/helpers_spec.rb b/spec/helpers_spec.rb index 96c4fe71..0e9b0e88 100644 --- a/spec/helpers_spec.rb +++ b/spec/helpers_spec.rb @@ -119,7 +119,7 @@ must_equal %(foo/bar/qux.html) 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 %(#{@helpers.full_name(code_object)}) + must_equal %(#{@helpers.full_name_for(code_object)}) end end @@ -157,7 +157,7 @@ module Foo; module Bar; end RUBY _(@helpers.link_to(rdoc_module)). - must_equal %(#{@helpers.full_name(rdoc_module)}) + must_equal %(#{@helpers.full_name_for(rdoc_module)}) _(@helpers.link_to("Bar", rdoc_module)). must_equal %(Bar) @@ -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,23 +233,23 @@ module Foo; def <<(*); end; end end end - describe "#full_name" do + describe "#full_name_for" do it "wraps name in " do - _(@helpers.full_name("Foo")).must_equal "Foo" + _(@helpers.full_name_for("Foo")).must_equal "Foo" end it "inserts word-break opportunities into module names" do - _(@helpers.full_name("Foo::Bar::Qux")).must_equal "Foo::Bar::Qux" - _(@helpers.full_name("::Foo::Bar::Qux")).must_equal "::Foo::Bar::Qux" + _(@helpers.full_name_for("Foo::Bar::Qux")).must_equal "Foo::Bar::Qux" + _(@helpers.full_name_for("::Foo::Bar::Qux")).must_equal "::Foo::Bar::Qux" end it "inserts word-break opportunities into file paths" do - _(@helpers.full_name("path/to/file.rb")).must_equal "path/to/file.rb" - _(@helpers.full_name("/path/to/file.rb")).must_equal "/path/to/file.rb" + _(@helpers.full_name_for("path/to/file.rb")).must_equal "path/to/file.rb" + _(@helpers.full_name_for("/path/to/file.rb")).must_equal "/path/to/file.rb" end it "escapes name parts" do - _(@helpers.full_name("ruby&rails/file.rb")).must_equal "ruby&rails/file.rb" + _(@helpers.full_name_for("ruby&rails/file.rb")).must_equal "ruby&rails/file.rb" end it "uses RDoc::CodeObject#full_name when argument is an RDoc::CodeObject" do @@ -257,17 +257,17 @@ module Foo; def <<(*); end; end module Foo; module Bar; class Qux; end; end; end RUBY - _(@helpers.full_name(rdoc_module)).must_equal "Foo::Bar::Qux" + _(@helpers.full_name_for(rdoc_module)).must_equal "Foo::Bar::Qux" end end - describe "#short_name" do + describe "#short_name_for" do it "wraps name in " do - _(@helpers.short_name("foo")).must_equal "foo" + _(@helpers.short_name_for("foo")).must_equal "foo" end it "escapes the name" do - _(@helpers.short_name("<=>")).must_equal "<=>" + _(@helpers.short_name_for("<=>")).must_equal "<=>" end it "uses RDoc::CodeObject#name when argument is an RDoc::CodeObject" do @@ -275,7 +275,27 @@ module Foo; module Bar; class Qux; end; end; end module Foo; def bar; end; end RUBY - _(@helpers.short_name(rdoc_method)).must_equal "bar" + _(@helpers.short_name_for(rdoc_method)).must_equal "bar" + 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 %(
    \n

    This is Foo.

    \n
    ) + 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
    <%= short_name const %><%= short_name_for const %> = <%= h const.value %>
      <%= const.description.strip %> [<%= attrib.rw %>] <%= short_name attrib %><%= short_name_for attrib %> <%= attrib.description.strip %>