- Clarify how desc/doc strings are automatically extracted
- Clarify in the example where my_parameter comes from
- add subheadings to Writing Compatible Documentation
Do a bit of renaming and add some comments to make the processing
of parameter details a bit more clear. Additionally, update the
example in the README so that it will actually be parsed properly
by YARD (since YARD does not expect the one line title before the
description).
Running `puppet strings server` generates documentation for all
modules in your modulepath, meaning that it also generates HTML
for strings itself. Since there are parts of strings that are not
meant to be documented with YARD, exclude the files that cause
error messages so that `puppet strings server` is not needlessly
noisy.
Additionally, make a few suggested changes to the README to make
it clearer and easier to read.
In order to make it easier for users, give some basic examples
in the README of how write documentation that is compatible with
strings. Also provide a few resources for getting started.
The instructions for installation provided a lot of different
alternatives. In order to quickly answer the question of "how do I use
this" we can just give the most common ways of getting it installed.
Since we don't want the name of the tool to reflect the fact that
it is using yard internally (this is an implementation detail), rename
the face to `strings`. Now when one wishes to generate documentation,
`puppet strings` will be used rather than `puppet yardoc`.
David Danzilio