(PDOC-184) implemented option and raises tags

This implements the two remaining tags and removes the author tag. Had to do some deeper plumbing because options per function signature were not being passed along from YARD

lib/puppet-strings/json.rb

@@ -34,6 +34,13 @@ module PuppetStrings::Json
       next t.to_hash if t.respond_to?(:to_hash)
 
       tag = { tag_name: t.tag_name }
+      # grab nested information for @option tags
+      if tag[:tag_name] == 'option'
+        tag[:opt_name] = t.pair.name
+        tag[:opt_text] = t.pair.text
+        tag[:opt_types] = t.pair.types
+        tag[:parent] = t.name
+      end
       tag[:text] = t.text if t.text
       tag[:types] = t.types if t.types
       tag[:name] = t.name if t.name

lib/puppet-strings/markdown/base.rb

@@ -58,8 +58,6 @@ module PuppetStrings::Markdown
     { :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?
@@ -101,6 +99,20 @@ module PuppetStrings::Markdown
       @tags.select { |tag| tag[:tag_name] == 'example' } unless @tags.select { |tag| tag[:tag_name] == 'example' }[0].nil?
     end
 
+    # @return [Array] example tag hashes
+    def raises
+      @tags.select { |tag| tag[:tag_name] == 'raise' } unless @tags.select { |tag| tag[:tag_name] == 'raise' }[0].nil?
+    end
+
+    def options
+      @tags.select { |tag| tag[:tag_name] == 'option' } unless @tags.select { |tag| tag[:tag_name] == 'option' }[0].nil?
+    end
+
+    def options_for_param(parameter_name)
+      opts_for_p = options.select { |o| o[:parent] == parameter_name } unless options.nil?
+      opts_for_p unless opts_for_p.nil? || opts_for_p.length == 0
+    end
+
     # @return [Array] any defaults found for the component
     def defaults
       @registry[:defaults] unless @registry[:defaults].nil?

lib/puppet-strings/markdown/puppet_function.rb

@@ -16,6 +16,27 @@ module PuppetStrings::Markdown
     def render
       super(@template)
     end
+
+    def type
+      t = @registry[:type]
+      if t =~ /ruby4x/
+        "Ruby 4.x API"
+      elsif t =~ /ruby3/
+        "Ruby 3.x API"
+      elsif t =~ /ruby/
+        "Ruby"
+      else
+        "Puppet Language"
+      end
+    end
+
+    def error_type(r)
+      "`#{r.split(' ')[0]}`"
+    end
+
+    def error_text(r)
+      "#{r.split(' ').drop(1).join(' ')}"
+    end
   end
 
   class PuppetFunction::Signature < Base

lib/puppet-strings/markdown/puppet_resource_type.rb

@@ -20,7 +20,8 @@ module PuppetStrings::Markdown
     end
 
     def regex_in_data_type?(data_type)
-      data_type.match(/\w+\[\/.*\/\]/).length > 0
+      m = data_type.match(/\w+\[\/.*\/\]/)
+      m unless m.nil? || m.length.zero?
     end
   end
 end

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

@@ -1,4 +1,5 @@
 ### <%= name %>
+Type: <%= type %>
 
 <% signatures.each do |sig| -%>
 #### `<%= sig.signature %>`
@@ -10,6 +11,13 @@
 <% if sig.return_val -%>
 Returns: `<%= sig.return_type %>` <%= sig.return_val %>
 
+<% end -%>
+<% if raises -%>
+Raises:
+<% raises.each do |r| -%>
+* <%= error_type(r[:text]) %> <%= error_text(r[:text]) %>
+<% end -%>
+
 <% end -%>
 <% if sig.params -%>
 <% sig.params.each do |param| -%>
@@ -19,6 +27,14 @@ Data type: `<%= param[:types][0] %>`
 
 <%= param[:text] %>
 
+<% if sig.options_for_param(param[:name]) -%>
+Options:
+
+<% sig.options_for_param(param[:name]).each do |o| -%>
+* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+<% end -%>
+
+<% end -%>
 <% end -%>
 <% end -%>
 <% end -%>

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

@@ -9,10 +9,6 @@
 <% see.each do |sa| -%>
 <%= sa[:name] %>
 <%= sa[:text] %>
-<% end -%>
-<% if author -%>
-* **Author** <%= author %>
-
 <% end -%>
 
 <% end -%>
@@ -40,6 +36,14 @@ Data type: `<%= param[:types].join(', ') -%>`
 <% end -%>
 <%= param[:text] %>
 
+<% if options_for_param(param[:name]) -%>
+Options:
+
+<% options_for_param(param[:name]).each do |o| -%>
+* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+<% end -%>
+
+<% end -%>
 <% if defaults && defaults[param[:name]] -%>
 Default value: <%= value_string(defaults[param[:name]]) %>
 

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

@@ -8,17 +8,13 @@
 * **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| -%>
@@ -39,17 +35,29 @@ The following properties are available in the `<%= name %>` <%= @type %>.
 <% if prop[:values] -%>
 Valid values: <%= prop[:values].map { |value| value_string(value) }.join(', ') %>
 
+<% end -%>
+<% if prop[:isnamevar] -%>
+namevar
+
 <% end -%>
 <% if prop[:aliases] -%>
 Aliases: <%= prop[:aliases].to_s.delete('{').delete('}') %>
 
 <% end -%>
 <% if prop[:data_type] -%>
-Data type: `<%= prop[:data_type] %>`
+Data type: `<%= prop[:data_type] %>`<%= "\n_\*this data type contains a regex that may not be accurately reflected in generated documentation_" if regex_in_data_type?(prop[:data_type]) %>
 
 <% end -%>
 <%= prop[:description] %>
 
+<% if options_for_param(prop[:name]) -%>
+Options:
+
+<% options_for_param(prop[:name]).each do |o| -%>
+* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+<% end -%>
+
+<% end -%>
 <% if prop[:default] -%>
 Default value: <%= prop[:default] %>
 
@@ -71,6 +79,10 @@ Valid values: <%= param[:values].map { |value| value_string(value) }.join(', ')
 <% if param[:isnamevar] -%>
 namevar
 
+<% end -%>
+<% if param[:aliases] -%>
+Aliases: <%= param[:aliases].to_s.delete('{').delete('}') %>
+
 <% end -%>
 <% if param[:data_type] -%>
 Data type: `<%= param[:data_type] %>`<%= "\n_\*this data type contains a regex that may not be accurately reflected in generated documentation_" if regex_in_data_type?(param[:data_type]) %>
@@ -78,6 +90,14 @@ Data type: `<%= param[:data_type] %>`<%= "\n_\*this data type contains a regex t
 <% end -%>
 <%= param[:description] %>
 
+<% if options_for_param(param[:name]) -%>
+Options:
+
+<% options_for_param(param[:name]).each do |o| -%>
+* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+<% end -%>
+
+<% end -%>
 <% if param[:default] -%>
 Default value: <%= value_string(param[:default]) %>
 

lib/puppet-strings/yard/code_objects/function.rb

@@ -84,14 +84,14 @@ class PuppetStrings::Yard::CodeObjects::Function < PuppetStrings::Yard::CodeObje
     hash[:line] = line
     hash[:type] = @function_type.to_s
     hash[:signatures] = []
-    
+
     if self.has_tag? :overload
       # loop over overloads and append onto the signatures array
       self.tags(:overload).each do |o|
-        hash[:signatures] << { :signature => o.signature, :docstring => PuppetStrings::Json.docstring_to_hash(o.docstring, [:param, :return]) }
+        hash[:signatures] << { :signature => o.signature, :docstring => PuppetStrings::Json.docstring_to_hash(o.docstring, [:param, :option, :return]) }
       end
     else
-      hash[:signatures] << { :signature => self.signature, :docstring =>  PuppetStrings::Json.docstring_to_hash(docstring, [:param, :return]) }
+      hash[:signatures] << { :signature => self.signature, :docstring =>  PuppetStrings::Json.docstring_to_hash(docstring, [:param, :option, :return]) }
     end
 
     hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring)

spec/fixtures/unit/markdown/output.md

@@ -20,8 +20,6 @@
 * **See also**
 www.puppet.com
 
-* **Author** eputnam
-
 
 #### Examples
 ##### This is an example
@@ -32,6 +30,14 @@ class { 'klass':
 }
 ```
 
+##### This is another example
+```puppet
+class { 'klass':
+  param1 => 1,
+  param3 => 'foo',
+}
+```
+
 
 #### Parameters
 
@@ -51,6 +57,11 @@ Data type: `Any`
 
 Second param.
 
+Options:
+
+* **:opt1** `String`: something about opt1
+* **:opt2** `Hash`: a hash of stuff
+
 Default value: `undef`
 
 ##### `param3`
@@ -71,8 +82,6 @@ Default value: 'hi'
 * **See also**
 www.puppet.com
 
-* **Author** eputnam
-
 
 #### Examples
 ##### Here's an example of this type:
@@ -102,6 +111,11 @@ Data type: `Any`
 
 Second param.
 
+Options:
+
+* **:opt1** `String`: something about opt1
+* **:opt2** `Hash`: a hash of stuff
+
 ##### `param3`
 
 Data type: `String`
@@ -130,8 +144,6 @@ 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
@@ -174,8 +186,6 @@ The ID of the key you want to manage.
 
 An example database server resource type.
 
-* **Author** eputnam
-
 #### Examples
 ##### here's an example
 ```puppet
@@ -236,6 +246,7 @@ Default value: `false`
 ## Functions
 
 ### func
+Type: Puppet Language
 
 #### `func(Integer $param1, Any $param2, String $param3 = hi)`
 
@@ -243,6 +254,9 @@ A simple Puppet function.
 
 Returns: `Undef` Returns nothing.
 
+Raises:
+* `SomeError` this is some error
+
 ##### `param1`
 
 Data type: `Integer`
@@ -261,7 +275,12 @@ Data type: `String`
 
 Third param.
 
+Options:
+
+* **:param3opt** `Array`: Something about this option
+
 ### func4x
+Type: Ruby 4.x API
 
 #### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)`
 
@@ -281,6 +300,11 @@ Data type: `Any`
 
 The second parameter.
 
+Options:
+
+* **:option** `String`: an option
+* **:option2** `String`: another option
+
 ##### `param3`
 
 Data type: `Optional[Array[String]]`
@@ -306,6 +330,7 @@ Data type: `Callable`
 The block parameter.
 
 ### func4x_1
+Type: Ruby 4.x API
 
 #### `func4x_1(Integer $param1)`
 

spec/unit/puppet-strings/markdown_spec.rb

@@ -17,12 +17,18 @@ describe PuppetStrings::Markdown do
 #    param1 => 1,
 #    param3 => 'foo',
 #  }
-# @author eputnam
-# @option opts :foo bar
+# @example This is another example
+#  class { 'klass':
+#    param1 => 1,
+#    param3 => 'foo',
+#  }
 # @raise SomeError
 # @param param1 First param.
 # @param param2 Second param.
+# @option param2 [String] :opt1 something about opt1
+# @option param2 [Hash] :opt2 a hash of stuff
 # @param param3 Third param.
+#
 class klass (
   Integer $param1 = 1,
   $param2 = undef,
@@ -40,11 +46,11 @@ 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.
+# @option param2 [String] :opt1 something about opt1
+# @option param2 [Hash] :opt2 a hash of stuff
 # @param param3 Third param.
 # @param param4 Fourth param.
 define klass::dt (
@@ -61,9 +67,8 @@ SOURCE
 # @param param1 First param.
 # @param param2 Second param.
 # @param param3 Third param.
-# @author eputnam
-# @option opts :foo bar
-# @raise SomeError
+# @option param3 [Array] :param3opt Something about this option
+# @raise SomeError this is some error
 # @return [Undef] Returns nothing.
 function func(Integer $param1, $param2, String $param3 = hi) {
 }
@@ -73,11 +78,11 @@ 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
+  # @raise SomeError this is some error
   # @param param1 The first parameter.
   # @param param2 The second parameter.
+  # @option param2 [String] :option an option
+  # @option param2 [String] :option2 another option
   # @param param3 The third parameter.
   # @return Returns nothing.
   dispatch :foo do
@@ -121,7 +126,6 @@ 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
@@ -169,7 +173,6 @@ 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
@@ -214,7 +217,7 @@ SOURCE
 
   describe 'rendering markdown to a file' do
     it 'should output the expected markdown content' do
-      Tempfile.open('md') do |file|
+      File.open('/Users/eric.putnam/src/puppet-strings/md.md', 'w') do |file|
         PuppetStrings::Markdown.render(file.path)
         expect(File.read(file.path)).to eq(baseline)
       end