From d2c178b59c7c1186aacb1feefab113eba7c6c1cc Mon Sep 17 00:00:00 2001
From: Ian Kronquist <iankronquist@teleport.com>
Date: Mon, 14 Sep 2015 15:14:31 -0700
Subject: [PATCH 1/3] (PDOC-52) Register docstring after object

In a Puppet type if the user documents a parameter with the directive, then
Yard will read the parameter and think there is an empty docstring there. This
will overwrite the docstring we extracted.
The fix is simple -- overwrite our docstring with theirs, if our docstring
exists at all.
---
 .../puppetlabs/strings/yard/handlers/type_handler.rb       | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/lib/puppet_x/puppetlabs/strings/yard/handlers/type_handler.rb b/lib/puppet_x/puppetlabs/strings/yard/handlers/type_handler.rb
index d146e6f2d..06c7d342e 100644
--- a/lib/puppet_x/puppetlabs/strings/yard/handlers/type_handler.rb
+++ b/lib/puppet_x/puppetlabs/strings/yard/handlers/type_handler.rb
@@ -138,9 +138,12 @@ class PuppetX::PuppetLabs::Strings::YARD::Handlers::PuppetTypeHandler < YARD::Ha
     obj.property_details = property_details
     obj.features = features
 
-    register_docstring(obj, docstring, nil)
-
     register obj
+    # Register docstring after the object. If the object already has a
+    # docstring, or more likely has parameters documented with the type
+    # directive and an empty docstring, we want to override it with the
+    # docstring we found, assuming we found one.
+    register_docstring(obj, docstring, nil) if docstring
   end
 
 

From 3a2f70026e05fb16c8fd6e4cc904678c633255c5 Mon Sep 17 00:00:00 2001
From: Ian Kronquist <iankronquist@teleport.com>
Date: Mon, 14 Sep 2015 15:20:34 -0700
Subject: [PATCH 2/3] (PDOC-52) Fix section on Type directives

This confusion persists from a very old attempt at implementing support for
types and providers.
---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 7c0862ab8..7e10275af 100644
--- a/README.md
+++ b/README.md
@@ -165,7 +165,7 @@ Here's an example of how you might document a class:
 Strings will automatically extract the `@doc` provider docstring and any `desc`
 parameter/property docstrings.
 
-Sometimes however, Puppet providers use metaprogramming to create parameters
+Sometimes however, Puppet types use metaprogramming to create parameters
 and methods automatically. In those cases Strings will not be able to document
 them automatically (Strings doesn't execute the code that would generate those
 parameters), so you will need to provide hints on how to document your code. To
@@ -174,7 +174,7 @@ directive `@!puppet.provider.param` which may take types, the parameter name,
 and a description.
 
 ```ruby
-# @!puppet.provider.param my_parameter This parameter needs to be explicitly
+# @!puppet.type.param my_parameter This parameter needs to be explicitly
 # documented as it is generated by mk_resource_methods
 Puppet::Type.newtype(:minifile) do
 

From 7f4b81e77ba6ab5f5a854e68e0daf02d7173379b Mon Sep 17 00:00:00 2001
From: Ian Kronquist <iankronquist@teleport.com>
Date: Mon, 14 Sep 2015 15:17:23 -0700
Subject: [PATCH 3/3] (PDOC-53) Handle directives with no types

Parameter directives with no types will have `tag.type` set to nil. We cannot
append nil to an array, so instead, place it in the array and flatten the
array. If the property is empty the second entry in the array will be nil, as
we expect. If the `tag.type` is an array of types we will have and array with
the form:
	[tag.text, type1, type2, type3, ...]
---
 lib/puppet_x/puppetlabs/strings/yard/tags/directives.rb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/puppet_x/puppetlabs/strings/yard/tags/directives.rb b/lib/puppet_x/puppetlabs/strings/yard/tags/directives.rb
index dcb60e084..0b9479306 100644
--- a/lib/puppet_x/puppetlabs/strings/yard/tags/directives.rb
+++ b/lib/puppet_x/puppetlabs/strings/yard/tags/directives.rb
@@ -3,7 +3,7 @@
 class PuppetX::PuppetLabs::Strings::YARD::Tags::PuppetTypeParameterDirective < YARD::Tags::Directive
   def call
     return if object.nil?
-    object.parameters << ([tag.text] + tag.types)
+    object.parameters << ([tag.text, tag.types].flatten)
     object.parameter_details << {:name => tag.name, :desc => tag.text, :exists? => true, :puppet_type => true}
   end
 end