(PDOC-184) implement author tag

This implements the author tag. We also claim to support the 'raise' and 'option' tags, but I don't know that we need to. This also consolidates some code in base.rb and adds docs

lib/puppet-strings/markdown/base.rb

@@ -3,6 +3,49 @@ require 'puppet-strings/json'
 require 'puppet-strings/yard'
 
 module PuppetStrings::Markdown
+  # This class makes elements in a YARD::Registry hash easily accessible for templates.
+  #
+  # Here's an example hash:
+  #{:name=>:klass,
+  # :file=>"(stdin)",
+  # :line=>16,
+  # :inherits=>"foo::bar",
+  # :docstring=>
+  #  {:text=>"An overview for a simple class.",
+  #   :tags=>
+  #    [{:tag_name=>"summary", :text=>"A simple class."},
+  #     {:tag_name=>"since", :text=>"1.0.0"},
+  #     {:tag_name=>"see", :name=>"www.puppet.com"},
+  #     {:tag_name=>"example",
+  #      :text=>
+  #       "class { 'klass':\n" +
+  #       "  param1 => 1,\n" +
+  #       "  param3 => 'foo',\n" +
+  #       "}",
+  #      :name=>"This is an example"},
+  #     {:tag_name=>"author", :text=>"eputnam"},
+  #     {:tag_name=>"option", :name=>"opts"},
+  #     {:tag_name=>"raise", :text=>"SomeError"},
+  #     {:tag_name=>"param",
+  #      :text=>"First param.",
+  #      :types=>["Integer"],
+  #      :name=>"param1"},
+  #     {:tag_name=>"param",
+  #      :text=>"Second param.",
+  #      :types=>["Any"],
+  #      :name=>"param2"},
+  #     {:tag_name=>"param",
+  #      :text=>"Third param.",
+  #      :types=>["String"],
+  #      :name=>"param3"}]},
+  # :defaults=>{"param1"=>"1", "param2"=>"undef", "param3"=>"'hi'"},
+  # :source=>
+  #  "class klass (\n" +
+  #  "  Integer $param1 = 1,\n" +
+  #  "  $param2 = undef,\n" +
+  #  "  String $param3 = 'hi'\n" +
+  #  ") inherits foo::bar {\n" +
+  #  "}"}
   class Base
     def initialize(registry, component_type)
       @type = component_type
@@ -10,18 +53,30 @@ module PuppetStrings::Markdown
       @tags = registry[:docstring][:tags] || []
     end
 
+    # generate 1:1 tag methods
+    # e.g. {:tag_name=>"author", :text=>"eputnam"}
+    { :return_val => 'return',
+      :since => 'since',
+      :summary => 'summary',
+      :author => 'author',
+      :raise => 'raise',
+      :option => 'option' }.each do |method_name, tag_name|
+      define_method method_name do
+        @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0][:text] unless @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0].nil?
+      end
+    end
+
+    # @return [String] top-level name
     def name
       @registry[:name].to_s unless @registry[:name].nil?
     end
 
+    # @return [String] 'Overview' text (untagged text)
     def text
       @registry[:docstring][:text] unless @registry[:docstring][:text].empty?
     end
 
-    def return_val
-      @tags.select { |tag| tag[:tag_name] == 'return' }[0][:text] unless @tags.select { |tag| tag[:tag_name] == 'return' }[0].nil?
-    end
-
+    # @return [String] data type of return value
     def return_type
       @tags.select { |tag| tag[:tag_name] == 'return' }[0][:types][0] unless @tags.select { |tag| tag[:tag_name] == 'return' }[0].nil?
     end
@@ -31,26 +86,27 @@ module PuppetStrings::Markdown
       @tags.select { |tag| tag[:tag_name] == 'since' }[0][:text] unless @tags.select { |tag| tag[:tag_name] == 'since' }[0].nil?
     end
 
-    # return [Array] array of @see tag hashes
+    # @return [Array] @see tag hashes
     def see
       @tags.select { |tag| tag[:tag_name] == 'see' } unless @tags.select { |tag| tag[:tag_name] == 'see' }[0].nil?
     end
 
-    # return [String] text from @summary tag
-    def summary
-      @tags.select { |tag| tag[:tag_name] == 'summary' }[0][:text] unless @tags.select { |tag| tag[:tag_name] == 'summary' }[0].nil?
-    end
-
-    # return [Array] array of parameter tag hashes
+    # @return [Array] parameter tag hashes
     def params
       @tags.select { |tag| tag[:tag_name] == 'param' } unless @tags.select { |tag| tag[:tag_name] == 'param' }[0].nil?
     end
 
-    # return [Array] array of example tag hashes
+    # @return [Array] example tag hashes
     def examples
       @tags.select { |tag| tag[:tag_name] == 'example' } unless @tags.select { |tag| tag[:tag_name] == 'example' }[0].nil?
     end
 
+    # @return [Array] any defaults found for the component
+    def defaults
+      @registry[:defaults] unless @registry[:defaults].nil?
+    end
+
+    # @return [Hash] information needed for the table of contents
     def toc_info
       {
         name: name.to_s,
@@ -59,14 +115,15 @@ module PuppetStrings::Markdown
       }
     end
 
+    # @return [String] makes the component name suitable for a GitHub markdown link
     def link
       name.delete('::').strip.gsub(' ','-').downcase
     end
 
-    def defaults
-      @registry[:defaults] unless @registry[:defaults].nil?
-    end
-
+    # Some return, default, or valid values need to be in backticks. Instead of fu in the handler or code_object, this just does the change on the front.
+    # @param value
+    #  any string
+    # @return [String] value or value in backticks if it is in a list
     def value_string(value)
       to_symbol = %w[undef true false]
       if to_symbol.include? value
@@ -76,6 +133,7 @@ module PuppetStrings::Markdown
       end
     end
 
+    # @return [String] full markdown rendering of a component
     def render(template)
       file = File.join(File.dirname(__FILE__),"templates/#{template}")
       ERB.new(File.read(file), nil, '-').result(binding)

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

@@ -9,6 +9,10 @@
 <% see.each do |sa| -%>
 <%= sa[:name] %>
 <%= sa[:text] %>
+<% end -%>
+<% if author -%>
+* **Author** <%= author %>
+
 <% end -%>
 
 <% end -%>

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

@@ -8,13 +8,17 @@
 * **See also**
 <% see.each do |sa| -%>
 <%= sa[:name] %>
-<%= sa[:text] %>
+    <%= sa[:text] %>
 <% end -%>
 
 <% end -%>
 <% if text -%>
 <%= text %>
 <% end %>
+<% if author -%>
+* **Author** <%= author %>
+
+<% end -%>
 <% if examples -%>
 #### Examples
 <% examples.each do |eg| -%>

spec/fixtures/unit/markdown/output.md

@@ -20,6 +20,8 @@
 * **See also**
 www.puppet.com
 
+* **Author** eputnam
+
 
 #### Examples
 ##### This is an example
@@ -69,6 +71,8 @@ Default value: 'hi'
 * **See also**
 www.puppet.com
 
+* **Author** eputnam
+
 
 #### Examples
 ##### Here's an example of this type:
@@ -126,6 +130,8 @@ be manipulated through the `apt-key` command.
 If Puppet is given the location of a key file which looks like an absolute
 path this type will autorequire that file.
 
+* **Author** eputnam
+
 #### Examples
 ##### here's an example
 ```puppet
@@ -168,6 +174,8 @@ The ID of the key you want to manage.
 
 An example database server resource type.
 
+* **Author** eputnam
+
 #### Examples
 ##### here's an example
 ```puppet

spec/unit/puppet-strings/markdown_spec.rb

@@ -17,6 +17,9 @@ describe PuppetStrings::Markdown do
 #    param1 => 1,
 #    param3 => 'foo',
 #  }
+# @author eputnam
+# @option opts :foo bar
+# @raise SomeError
 # @param param1 First param.
 # @param param2 Second param.
 # @param param3 Third param.
@@ -37,6 +40,9 @@ class klass (
 #    param4 => false,
 #  }
 # @return shouldn't return squat
+# @author eputnam
+# @option opts :foo bar
+# @raise SomeError
 # @param param1 First param.
 # @param param2 Second param.
 # @param param3 Third param.
@@ -55,6 +61,9 @@ SOURCE
 # @param param1 First param.
 # @param param2 Second param.
 # @param param3 Third param.
+# @author eputnam
+# @option opts :foo bar
+# @raise SomeError
 # @return [Undef] Returns nothing.
 function func(Integer $param1, $param2, String $param3 = hi) {
 }
@@ -64,6 +73,9 @@ SOURCE
 # An example 4.x function.
 Puppet::Functions.create_function(:func4x) do
   # An overview for the first overload.
+  # @author eputnam
+  # @option opts :foo bar
+  # @raise SomeError
   # @param param1 The first parameter.
   # @param param2 The second parameter.
   # @param param3 The third parameter.
@@ -109,6 +121,9 @@ end
 Puppet::Type.newtype(:database) do
   desc <<-DESC
 An example database server resource type.
+@author eputnam
+@option opts :foo bar
+@raise SomeError
 @example here's an example
  database { 'foo':
    address => 'qux.baz.bar',
@@ -154,7 +169,8 @@ Puppet::ResourceApi.register_type(
   name: 'apt_key',
   desc: <<-EOS,
 @summary Example resource type using the new API.
-
+@author eputnam
+@raise SomeError
 This type provides Puppet with the capabilities to manage GPG keys needed
 by apt to perform package validation. Apt has it's own GPG keyring that can
 be manipulated through the `apt-key` command.