From 0883beadeb14eca896d443893c13e31603357da7 Mon Sep 17 00:00:00 2001 From: Rob Reynolds Date: Thu, 10 Sep 2015 10:47:12 -0500 Subject: [PATCH] (PDOC-35) Clarify types and providers example - Clarify how desc/doc strings are automatically extracted - Clarify in the example where my_parameter comes from - add subheadings to Writing Compatible Documentation --- README.md | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 30395da..7c0862a 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ Installing Strings Itself Strings can be installed from the [Puppet Forge][forge strings] or from source. -[forge strings]: https://forge.puppetlabs.com/puppetlabs/strings +[forge strings]: https://forge.puppetlabs.com/puppetlabs/strings **Installing from the Forge** @@ -119,6 +119,7 @@ future, here are some very basic examples to get you started using the strings module. These are very much subject to change as we continue to work out a style guide. +### Functions Here's an example of how you might document a 4x function: ``` @@ -140,7 +141,9 @@ Here's an example of how you might document a 4x function: end ``` -And here's an example of how you might document a class: +### Classes / Defined Types + +Here's an example of how you might document a class: ``` # This class is meant to serve as an example of how one might @@ -158,19 +161,21 @@ 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. - +### Types and Providers Strings will automatically extract the `@doc` provider docstring and any `desc` -parameter docstrings. +parameter/property docstrings. + +Sometimes however, Puppet providers 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 +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. ```ruby # @!puppet.provider.param my_parameter This parameter needs to be explicitly -# documented +# documented as it is generated by mk_resource_methods Puppet::Type.newtype(:minifile) do @doc = "Manages files, including their content, ownership, and permissions.