(puppetlabs#223) Use code blocks as appropriate in Markdown

Sometimes data types, default values, and other code outputted in
Markdown documentation is multiline. When that’s the case, it’s cleaner
to use a code block (below) rather and inline code (`code`).

```
example code block
with two lines
```

This updates the Markdown template code to use code blocks in many
places if the code in question contains a newline.

Thanks to @crazymind1337 for the example of a multiline type alias!

Author: danielparks

lib/puppet-strings/markdown/base.rb

@@ -3,6 +3,7 @@
 require 'puppet-strings'
 require 'puppet-strings/json'
 require 'puppet-strings/yard'
+require 'puppet-strings/markdown/helpers'
 
 module PuppetStrings::Markdown
   # This class makes elements in a YARD::Registry hash easily accessible for templates.
@@ -49,6 +50,9 @@ module PuppetStrings::Markdown
   #  ") inherits foo::bar {\n" +
   #  "}"}
   class Base
+    # Helpers for ERB templates
+    include PuppetStrings::Markdown::Helpers
+
     def initialize(registry, component_type)
       @type = component_type
       @registry = registry

lib/puppet-strings/markdown/helpers.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module PuppetStrings::Markdown::Helpers
+  # Formats code as either inline or a block.
+  #
+  # Note that this does not do any escaping even if the code contains ` or ```.
+  #
+  # @param [String] code The code to format.
+  # @param [Symbol] type The type of the code, e.g. :text, :puppet, or :ruby.
+  # @param [String] block_prefix String to insert before if it’s a block.
+  # @param [String] inline_prefix String to insert before if it’s inline.
+  # @returns [String] Markdown
+  def code_maybe_block(code, type: :puppet, block_prefix: "\n\n", inline_prefix: " ")
+    if code.include?("\n")
+      "#{block_prefix}```#{type.to_s}\n#{code}\n```"
+    else
+      "#{inline_prefix}`#{code}`"
+    end
+  end
+end
+

lib/puppet-strings/markdown/templates/classes_and_defines.erb

@@ -57,7 +57,7 @@ The following parameters are available in the `<%= name %>` <%= @type %>:
 ##### <a name="<%= param[:link] %>"></a>`<%= param[:name] %>`
 
 <% if param[:types] -%>
-Data type: `<%= param[:types].join(', ') -%>`
+Data type:<%= code_maybe_block(param[:types].join(', ')) %>
 
 <% end -%>
 <%= param[:text] %>
@@ -79,7 +79,7 @@ Options:
 
 <% end -%>
 <% if defaults && defaults[param[:name]] -%>
-Default value: `<%= defaults[param[:name]] %>`
+Default value:<%= code_maybe_block(defaults[param[:name]]) %>
 
 <% end -%>
 <% end -%>

lib/puppet-strings/markdown/templates/data_type.erb

@@ -45,11 +45,7 @@
 <% end -%>
 <% end -%>
 <% if alias_of -%>
-Alias of
-
-```puppet
-<%= alias_of %>
-```
+Alias of<%= code_maybe_block(alias_of) %>
 
 <% end -%>
 <% if params -%>
@@ -65,7 +61,7 @@ The following parameters are available in the `<%= name %>` <%= @type %>:
 ##### <a name="<%= param[:link] %>"></a>`<%= param[:name] %>`
 
 <% if param[:types] -%>
-Data type: `<%= param[:types].join(', ') -%>`
+Data type:<%= code_maybe_block(param[:types].join(', ')) %>
 
 <% end -%>
 <%= param[:text] %>
@@ -87,7 +83,7 @@ Options:
 
 <% end -%>
 <% if defaults && defaults[param[:name]] -%>
-Default value: `<%= defaults[param[:name]] %>`
+Default value:<%= code_maybe_block(defaults[param[:name]]) %>
 
 <% end -%>
 <% end -%>

lib/puppet-strings/markdown/templates/data_type_function.erb

@@ -43,7 +43,7 @@ Raises:
 <% params.each do |param| -%>
 ##### `<%= param[:name]  %>`
 
-Data type: `<%= param[:types][0] %>`
+Data type:<%= code_maybe_block(param[:types][0]) %>
 
 <%= param[:text] %>
 

lib/puppet-strings/markdown/templates/function.erb

@@ -77,7 +77,7 @@ Raises:
 <% sig.params.each do |param| -%>
 ##### `<%= param[:name]  %>`
 
-Data type: `<%= param[:types][0] %>`
+Data type:<%= code_maybe_block(param[:types][0]) %>
 
 <%= param[:text] %>
 

lib/puppet-strings/markdown/templates/puppet_task.erb

@@ -19,7 +19,7 @@
 ##### `<%= param[:name] %>`
 
 <% if param[:types] -%>
-Data type: `<%= param[:types].join(', ') -%>`
+Data type:<%= code_maybe_block(param[:types].join(', ')) %>
 
 <% end -%>
 <%= param[:text] %>

lib/puppet-strings/markdown/templates/resource_type.erb

@@ -87,7 +87,7 @@ Options:
 
 <% end -%>
 <% if prop[:default] -%>
-Default value: `<%= prop[:default] %>`
+Default value:<%= code_maybe_block(prop[:default], type: :ruby) %>
 
 <% end -%>
 <% end -%>

spec/unit/puppet-strings/markdown_spec.rb

@@ -260,4 +260,86 @@ def parse_data_type_content
 
     MARKDOWN
   end
+
+  it 'renders single-line data types with inline code' do
+    expect(YARD::Parser::SourceParser.parse_string(<<~'PUPPET', :puppet).enumerator.length).to eq(1)
+      # @summary it’s for testing
+      type MyEnum = Enum[a, b]
+    PUPPET
+
+    expect(described_class.generate).to match(%r{^Alias of `Enum\[a, b\]`$})
+  end
+
+  it 'renders multi-line data types with inline code' do
+    expect(YARD::Parser::SourceParser.parse_string(<<~'PUPPET', :puppet).enumerator.length).to eq(1)
+      # summary Test Type
+      #
+      type Test_module::Test_type = Hash[
+        Pattern[/^[a-z][a-z0-9_-]*$/],
+        Struct[
+          {
+            param1 => String[1],
+            param2 => Stdlib::Absolutepath,
+            paramX => Boolean,
+          }
+        ]
+      ]
+    PUPPET
+
+    expect(described_class.generate).to include(<<~'MARKDOWN')
+      Alias of
+
+      ```puppet
+      Hash[Pattern[/^[a-z][a-z0-9_-]*$/], Struct[
+          {
+            param1 => String[1],
+            param2 => Stdlib::Absolutepath,
+            paramX => Boolean,
+          }
+        ]]
+      ```
+    MARKDOWN
+  end
+
+  it 'renders single-line default values with inline code' do
+    expect(YARD::Parser::SourceParser.parse_string(<<~'PUPPET', :puppet).enumerator.length).to eq(1)
+      # @summary Test
+      class myclass (
+        String $os = 'linux',
+      ) {
+      }
+    PUPPET
+
+    expect(described_class.generate).to include(<<~'MARKDOWN')
+      Default value: `'linux'`
+    MARKDOWN
+  end
+
+  it 'renders multi-line default values with a code block' do
+    skip('Broken by https://tickets.puppetlabs.com/browse/PUP-11632')
+
+    expect(YARD::Parser::SourceParser.parse_string(<<~'PUPPET', :puppet).enumerator.length).to eq(1)
+      # @summary Test
+      class myclass (
+        String $os = $facts['kernel'] ? {
+          'Linux'  => 'linux',
+          'Darwin' => 'darwin',
+          default  => $facts['kernel'],
+        },
+      ) {
+      }
+    PUPPET
+
+    expect(described_class.generate).to include(<<~'MARKDOWN')
+      Default value:
+
+      ```puppet
+      $facts['kernel'] ? {
+          'Linux'  => 'linux',
+          'Darwin' => 'darwin',
+          default  => $facts['kernel']
+        }
+      ```
+    MARKDOWN
+  end
 end