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

Merge pull request #99 from peterhuene/readme 

(maint) Minor fixes to README.
This commit is contained in:
Will Hopper 2016-09-16 10:38:10 -07:00 committed by GitHub
parent 7ae8e74ec5 e396000f3d
commit ef651fb33a
1 changed files with 10 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
README.md
View File

@ -86,7 +86,7 @@ $ puppet strings generate first.pp second.pp ...
To document specific directories: To document specific directories:
``` ```
$ puppet strings 'modules/foo/lib/**/*.rb' 'modules/foo/manifests/**/*.pp' 'modules/foo/functions/**/*.pp' ... $ puppet strings generate 'modules/foo/lib/**/*.rb' 'modules/foo/manifests/**/*.pp' 'modules/foo/functions/**/*.pp' ...
``` ```
Strings can emit JSON documenting the Puppet extensions: Strings can emit JSON documenting the Puppet extensions:
@ -151,8 +151,8 @@ define example_type(
} }
``` ```
***Note: unlike Ruby, Puppet is a typed language; Puppet Strings will automatically use the parameter type information to ***Note: unlike Ruby, Puppet 4.x is a typed language; Puppet Strings will automatically use the parameter type information to
document the parameters. A warning will be emitted if you document parameter types.*** document the parameter types. A warning will be emitted if you document a parameter's type for a parameter that has a Puppet type specifier.***
### Resource Types ### Resource Types
@ -218,7 +218,7 @@ Puppet Strings documents this way to preserve backwards compatibility with `pupp
Puppet Strings supports three different ways of defining a function in Puppet: with the Puppet 3.x API, Puppet 4.X API, Puppet Strings supports three different ways of defining a function in Puppet: with the Puppet 3.x API, Puppet 4.X API,
and in the Puppet language itself. and in the Puppet language itself.
## Puppet 3.x API #### Puppet 3.x Functions
To document a function in the Puppet 3.x API, use the `doc` option to `newfunction`: To document a function in the Puppet 3.x API, use the `doc` option to `newfunction`:
@ -238,7 +238,7 @@ end
***Note: if parameter types are omitted, a default of the `Any` Puppet type will be used.*** ***Note: if parameter types are omitted, a default of the `Any` Puppet type will be used.***
## Puppet 4.x API #### Puppet 4.x Functions
To document a function in the Puppet 4.x API, use a YARD docstring before the `create_function` call and any `dispatch` To document a function in the Puppet 4.x API, use a YARD docstring before the `create_function` call and any `dispatch`
calls: calls:
@ -261,7 +261,7 @@ end
``` ```
***Note: Puppet Strings will automatically use the parameter type information from the `dispatch` block to document ***Note: Puppet Strings will automatically use the parameter type information from the `dispatch` block to document
the parameters. Only document your parameter types when the Puppet 4.x function contains no `dispatch` calls.*** the parameter types. Only document your parameter types when the Puppet 4.x function contains no `dispatch` calls.***
If the Puppet 4.x function contains multiple `dispatch` calls, Puppet Strings will automatically create `overload` tags If the Puppet 4.x function contains multiple `dispatch` calls, Puppet Strings will automatically create `overload` tags
to describe the function's overloads: to describe the function's overloads:
@ -292,7 +292,7 @@ Puppet::Functions.create_function(:example) do
The resulting HTML for this example function will document both `example(String $first)` and `example(Integer $first)`. The resulting HTML for this example function will document both `example(String $first)` and `example(Integer $first)`.
## Puppet Language #### Puppet Language Functions
To document Puppet functions written in the Puppet language, use a YARD docstring before the function definition: To document Puppet functions written in the Puppet language, use a YARD docstring before the function definition:
@ -307,8 +307,8 @@ function example(String $name) {
} }
``` ```
***Note: Puppet Strings will automatically use the parameter type information from the function's parameters to document ***Note: Puppet Strings will automatically use the parameter type information from the function's parameter list to document
the parameters.*** the parameter types.***
Additional Resources Additional Resources
-------------------- --------------------
@ -353,7 +353,7 @@ The task accepts the following parameters:
An example of passing arguments to the `strings:generate` Rake task: An example of passing arguments to the `strings:generate` Rake task:
``` ```
$ rake strings:generate\['**/*.pp **/*.rb, true, true, markdown, --readme README.md'] $ rake strings:generate\['**/*{.pp\,.rb}, true, true, markdown, --readme README.md']
``` ```
The `strings:gh_pages:update` task will generate your Puppet Strings documentation to be made available via [GitHub Pages](https://pages.github.com/). It will: The `strings:gh_pages:update` task will generate your Puppet Strings documentation to be made available via [GitHub Pages](https://pages.github.com/). It will: