kienan
/
puppet-strings
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

(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
This commit is contained in:
Rob Reynolds 2015-09-10 10:47:12 -05:00
parent 811df7d84d
commit 0883beadeb
1 changed files with 16 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
README.md
View File

@ -53,7 +53,7 @@ Installing Strings Itself
Strings can be installed from the [Puppet Forge][forge strings] or from source. 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** **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 module. These are very much subject to change as we continue to work out a
style guide. style guide.
### Functions
Here's an example of how you might document a 4x function: 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 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 # 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 ### Types and Providers
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` 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 ```ruby
# @!puppet.provider.param my_parameter This parameter needs to be explicitly # @!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 Puppet::Type.newtype(:minifile) do
@doc = "Manages files, including their content, ownership, and permissions. @doc = "Manages files, including their content, ownership, and permissions.