From 9b8777c1b4cd6527e387f7088b4bb073962dbb69 Mon Sep 17 00:00:00 2001
From: Ian Kronquist <iankronquist@teleport.com>
Date: Tue, 11 Aug 2015 11:53:01 -0700
Subject: [PATCH] (PDOC-35) Document documenting puppet providers

Add instructions on how to use the `@!puppet.provider.param` directive to
document parameters which are created via metaprogramming.
---
 README.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/README.md b/README.md
index afcac96..30395da 100644
--- a/README.md
+++ b/README.md
@@ -158,6 +158,39 @@ And here's an example of how you might document a class:
      ) { }
 ```
 
+Puppet providers often rely on different types of metaprogramming to create
+parameters and methods. Since Strings does not execute the code which is being
+documented you must provide hints on how to document your code. To document a
+parameter which is automatically created you must use the special directive
+`@!puppet.provider.param` Which may take types, the parameter name, and a
+description.
+
+Strings will automatically extract the `@doc` provider docstring and any `desc`
+parameter docstrings.
+
+```ruby
+# @!puppet.provider.param my_parameter This parameter needs to be explicitly
+# documented
+Puppet::Type.newtype(:minifile) do
+
+  @doc = "Manages files, including their content, ownership, and permissions.
+    The provider can manage symbolic links."
+
+  # This function does some metaprogramming on the new type.
+  mk_resource_methods
+
+  newparam(:path) do
+    desc <<-'EOT'
+      The path to the file to manage.  Must be fully qualified.
+    EOT
+    # ... do stuff here
+  end
+  # ...
+end
+
+
+```
+
 Here are a few other good resources for getting started with documentation:
 
   * [Module README Template](https://docs.puppetlabs.com/puppet/latest/reference/modules_documentation.html)