Section on module docs is incomplete/inconsistent with other docs
|Assignee:||Nick Fagerlund||% Done:|
The Style Guide section on module documentation doesn’t match our own docs on puppet doc style, and appears to have at least a single line, maybe more, truncated from the top.
A snippet from the beginning of the Style Guide code:
# Full description of class here. # # == Parameters # # Document parameters here # # [*servers*] # Description of servers class parameter. e.g. "Specify one or more # upstream ntp servers as an array." # # == Variables
And from the wiki (http://projects.puppetlabs.com/projects/1/wiki/Puppet_Manifest_Documentation) – which is the only place I can find real docs on format:
# Class: users # # This class installs our default set of users in our servers # # Parameters: # $starting_uid: # this global variable is used to set the minimum uid used for our users # # Actions: # Install the default set of users: [dana,fox] #
For the record, the second matches my own usage and that which I’ve seen elsewhere.
#2 Updated by Cody Herriges almost 2 years ago
- Status changed from Needs Decision to Rejected
The format put forth by the style guide is proper rdoc and was agreed upon. This is not reflected in all the modules we publish but the template we generate has been updated in puppet core.
#3 Updated by Eric Shamow almost 2 years ago
- Status changed from Rejected to Re-opened
Sorry to re-open, but the issue is the mismatch. I have no preference for which format we use, but one of the two needs to be corrected.
Additionally the style guide is still apparently missing info – it seems that lines are missing from the top of the Style Guide section.