The Puppet Labs Issue Tracker has Moved: https://tickets.puppetlabs.com

Bug #9927

Section on module docs is incomplete/inconsistent with other docs

Added by Anonymous about 3 years ago. Updated almost 3 years ago.

Status:ClosedStart date:10/05/2011
Priority:NormalDue date:
Assignee:Nick Fagerlund% Done:

0%

Category:style guide
Target version:-
Keywords: Affected URL:
Branch:

We've Moved!

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.


Description

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.

History

#1 Updated by James Turnbull about 3 years ago

  • Status changed from Unreviewed to Needs Decision
  • Assignee set to Nick Fagerlund

#2 Updated by Cody Herriges almost 3 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.

https://github.com/puppetlabs/puppet/blob/599a146386965f56b015530da59f3dd7cfc12415/lib/puppet/module_tool/skeleton/templates/generator/manifests/init.pp.erb

#3 Updated by Anonymous almost 3 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.

#4 Updated by Nick Fagerlund almost 3 years ago

Hmm. Yeah, let’s make them match. I’ll fix the wiki page immediately and take a second look at whatever I put in Learning Puppet. Eric, could you make any changes the style guide needs (re: the missing lines) and submit a pull request?

#5 Updated by Anonymous almost 3 years ago

  • Status changed from Re-opened to Closed

Nick,

Style guide actually looks ok now…I may have been looking in the wrong place or it’s been updated since. But this looks resolved to me.

-Eric

Also available in: Atom PDF