The Puppet Labs Issue Tracker has Moved: https://tickets.puppetlabs.com
Section on module docs is incomplete/inconsistent with other docs
|Assignee:||Nick Fagerlund||% Done:|
Ticket tracking is now hosted in JIRA: https://tickets.puppetlabs.com
This issue is currently not available for export. If you are experiencing the issue described below, please file a new ticket in JIRA. Once a new ticket has been created, please add a link to it that points back to this Redmine ticket.
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 over 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 Anonymous over 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.