From f6cd3ff4a881d6c63f27773e6273453b2a707d62 Mon Sep 17 00:00:00 2001
From: Eric Putnam <putnam.eric@gmail.com>
Date: Fri, 9 Feb 2018 15:08:18 -0800
Subject: [PATCH] (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                    |  7 ++++
 lib/puppet-strings/markdown/base.rb           | 16 +++++++-
 .../markdown/puppet_function.rb               | 21 ++++++++++
 .../markdown/puppet_resource_type.rb          |  3 +-
 .../markdown/templates/puppet_function.erb    | 16 ++++++++
 .../markdown/templates/puppet_resource.erb    | 12 ++++--
 .../templates/puppet_resource_type.erb        | 32 ++++++++++++---
 .../yard/code_objects/function.rb             |  6 +--
 spec/fixtures/unit/markdown/output.md         | 41 +++++++++++++++----
 spec/unit/puppet-strings/markdown_spec.rb     | 29 +++++++------
 10 files changed, 146 insertions(+), 37 deletions(-)

diff --git a/lib/puppet-strings/json.rb b/lib/puppet-strings/json.rb
index ae433c1..ff85a7e 100644
--- a/lib/puppet-strings/json.rb
+++ b/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
diff --git a/lib/puppet-strings/markdown/base.rb b/lib/puppet-strings/markdown/base.rb
index 1da38d1..1b16e54 100644
--- a/lib/puppet-strings/markdown/base.rb
+++ b/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?
diff --git a/lib/puppet-strings/markdown/puppet_function.rb b/lib/puppet-strings/markdown/puppet_function.rb
index cf39e54..d9024a6 100644
--- a/lib/puppet-strings/markdown/puppet_function.rb
+++ b/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
diff --git a/lib/puppet-strings/markdown/puppet_resource_type.rb b/lib/puppet-strings/markdown/puppet_resource_type.rb
index bb9cc3d..3d24fb3 100644
--- a/lib/puppet-strings/markdown/puppet_resource_type.rb
+++ b/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
diff --git a/lib/puppet-strings/markdown/templates/puppet_function.erb b/lib/puppet-strings/markdown/templates/puppet_function.erb
index 8be04f5..52ae63c 100644
--- a/lib/puppet-strings/markdown/templates/puppet_function.erb
+++ b/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 -%>
diff --git a/lib/puppet-strings/markdown/templates/puppet_resource.erb b/lib/puppet-strings/markdown/templates/puppet_resource.erb
index 02a57f2..8cf528c 100644
--- a/lib/puppet-strings/markdown/templates/puppet_resource.erb
+++ b/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]]) %>
 
diff --git a/lib/puppet-strings/markdown/templates/puppet_resource_type.erb b/lib/puppet-strings/markdown/templates/puppet_resource_type.erb
index 38b403f..12cff6f 100644
--- a/lib/puppet-strings/markdown/templates/puppet_resource_type.erb
+++ b/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]) %>
 
diff --git a/lib/puppet-strings/yard/code_objects/function.rb b/lib/puppet-strings/yard/code_objects/function.rb
index 4c2edf2..0ea3a93 100644
--- a/lib/puppet-strings/yard/code_objects/function.rb
+++ b/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)
diff --git a/spec/fixtures/unit/markdown/output.md b/spec/fixtures/unit/markdown/output.md
index d522036..b7177d5 100644
--- a/spec/fixtures/unit/markdown/output.md
+++ b/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)`
 
diff --git a/spec/unit/puppet-strings/markdown_spec.rb b/spec/unit/puppet-strings/markdown_spec.rb
index fcca460..fed6487 100644
--- a/spec/unit/puppet-strings/markdown_spec.rb
+++ b/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