Puppet Strings style guide

This style guide applies to:

• Puppet Strings version 2.0 or later

• Puppet 4.0 or later

Strings documentation comments inside module code follow these rules and guidelines:

• Place an element's documentation comment immediately before the code for that element. Do not put a blank line between the comment and its corresponding code.

• Each comment tag (such as @example) may have more than one line of comments. Indent additional lines with two spaces.

• Keep each comment line to no more than 140 characters, to improve readability.

• Separate comment sections (such as @summary, @example, or the @param list) with a blank comment line (that is, a # with no additional content), to improve readability.

• Untagged comments for a given element are output in an overview section that precedes all tagged information for that code element.

• If an element, such as a class or parameter, is deprecated, indicate it in the description for that element with Deprecated in bold.

Document each class and defined type, along with its parameters, with comments before the code. List the class and defined type information in the following order:

1. A @summary tag, a space, and then a summary describing the class or defined type.

2. Other tags such as @see, @note, or @api private.

3. Usage examples, each consisting of:

   1. An @example tag with a description of a usage example on the same line.

   2. A code example showing how the class or defined type is used. Place this example directly under the @example tag and description, indented two spaces.

4. One @param tag for each parameter in the class or defined type. See the parameters section for formatting guidelines.

Add parameter information as part of any class, defined type, or function that accepts parameters. Include the parameter information in the following order:

1. The @param tag, a space, and then the name of the parameter.

2. A description of what the parameter does. This may be either on the same line as the @param tag or on the next line, indented with two spaces.

3. Additional information about valid values that is not clear from the data type. For example, if the data type is [String], but the value must specifically be a path, say so here.

4. Other information about the parameter, such as warnings or special behavior. For example:

   # @param noselect_servers
   #   Specifies one or more peers to not sync with. Puppet appends 'noselect' to each matching item in the `servers` array.

# @summary configures the Apache PHP module
#
# @example Basic usage
#   class { 'apache::mod::php':
#     package_name => 'mod_php5',
#     source       => '/etc/php/custom_config.conf',
#     php_version  => '7',
#   }
#
# @see http://php.net/manual/en/security.apache.php
#
# @param package_name
#   Names the package that installs mod_php
# @param package_ensure
#   Defines ensure for the PHP module package
# @param path
#   Defines the path to the mod_php shared object (.so) file.
# @param extensions
#   Defines an array of extensions to associate with PHP.
# @param content
#   Adds arbitrary content to php.conf.
# @param template
#   Defines the path to the php.conf template Puppet uses to generate the configuration file.
# @param source
#   Defines the path to the default configuration. Values include a puppet:/// path.
# @param root_group
#   Names a group with root access
# @param php_version
#   Names the PHP version Apache is using.
#
class apache::mod::php (
  $package_name     = undef,
  $package_ensure   = 'present',
  $path             = undef,
  Array $extensions = ['.php'],
  $content          = undef,
  $template         = 'apache/mod/php.conf.erb',
  $source           = undef,
  $root_group       = $::apache::params::root_group,
  $php_version      = $::apache::params::php_version,
)
 {
 …
 }

# @summary
#   Create and configure a MySQL database.
#
# @example Create a database
#   mysql::db { 'mydb':
#     user     => 'myuser',
#     password => 'mypass',
#     host     => 'localhost',
#     grant    => ['SELECT', 'UPDATE'],
#   }
#
# @param name
#   The name of the database to create. (dbname)
# @param user
#   The user for the database you're creating.
# @param password
#   The password for $user for the database you're creating.
# @param dbname
#   The name of the database to create.
# @param charset
#   The character set for the database.
# @param collate
#   The collation for the database.
# @param host
#   The host to use as part of user@host for grants.
# @param grant
#   The privileges to be granted for user@host on the database.
# @param sql
#   The path to the sqlfile you want to execute. This can be single file specified as string, or it can be an array of strings.
# @param enforce_sql
#   Specifies whether to execute the sqlfiles on every run. If set to false, sqlfiles  runs only one time.
# @param ensure
#   Specifies whether to create the database. Valid values are 'present', 'absent'. Defaults to 'present'.
# @param import_timeout
#   Timeout, in seconds, for loading the sqlfiles. Defaults to 300.
# @param import_cat_cmd
#   Command to read the sqlfile for importing the database. Useful for compressed sqlfiles. For example, you can use 'zcat' for .gz files.

Include the following information for each function:

1. An untagged docstring describing what the function does.

2. One @param tag for each parameter in the function. See the parameters section for formatting guidelines.

3. A @return tag with the data type and a description of the returned value.

4. Optionally, a usage example, consisting of:

   1. An @example tag with a description of a usage example on the same line.

   2. A code example showing how the function is used. Place this example directly under the @example tag and description, indented two spaces.

# An example 4.x function.
Puppet::Functions.create_function(:example) do
  # @param first The first parameter.
  # @param second The second parameter.
  # @return [String] Returns a string.
  # @example Calling the function
  #   example('hi', 10)
  dispatch :example do
    param 'String', :first
    param 'Integer', :second
  end

  # ...
end

# An example 4.x function.
Puppet::Functions.create_function(:example) do
  # @param first The first parameter.
  # @param second The second parameter.
  # @return [String] If second argument is less than 10, the name of one item.
  # @return [Array] If second argument is greater than 10, a list of item names.
  # @example Calling the function.
  #   example('hi', 10)
  dispatch :example do
    param 'String', :first
    param 'Integer', :second
  end

  # ...
end

# @param name the name to say hello to.
# @return [String] Returns a string.
# @example Calling the function.
#    example(‘world’)
function example(String $name) {
    “hello, $name”
}

Document the resource type description in the following order:

1. Directly under the type definition, indented two spaces, the desc method, with a heredoc including a descriptive delimiting keyword, such as DESC.

2. A @summary tag with a summary describing the type.

3. Optionally, usage examples, each consisting of:

   1. An @example tag with a description of a usage example on the same line.

   2. Code example showing how the type is used. Place this example directly under the @example tag and description, indented two spaces.

Puppet::ResourceApi.register_type(
  name: 'apt_key',
  docs: <<-EOS,
@summary Fancy new type.
@example Fancy new example.
 apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F':
   source => 'http://apt.puppet.com/pubkey.gpg'
 }

This type provides Puppet with the capabilities to
manage GPG keys needed by apt to perform package validation. Apt has its own GPG keyring that can be manipulated through the `apt-key` command.

**Autorequires**:
If Puppet is given the location of a key file which looks like an absolute path this type will autorequire that file.
EOS
  attributes:   {
    ensure:      {
      type: 'Enum[present, absent]',
       desc: 'Whether this apt key should be present or absent on the target system.'**
    },
    id:          {
      type:      'Variant[Pattern[/\A(0x)?[0-9a-fA-F]{8}\Z/], Pattern[/\A(0x)?[0-9a-fA-F]{16}\Z/], Pattern[/\A(0x)?[0-9a-fA-F]{40}\Z/]]',
      behaviour: :namevar,
       desc:      'The ID of the key you want to manage.',**
    },
    # ...
    created:     {
      type:      'String',
      behavior: :read_only,
      desc:      'Date the key was created, in ISO format.',**
    },
  },
  autorequires: {
    file:    '$source', # will evaluate to the value of the `source` attribute
    package: 'apt',
  },
)

List the plan information in the following order:

1. A @summary tag, a space, and then a summary describing the plan.

2. Other tags such as @see, @note, or @api private.

3. Usage examples, each consisting of:

   1. An @example tag with a description of a usage example on the same line.

   2. Code example showing how the plan is used. Place this example directly under the @example tag and description, indented two spaces.

4. One @param tag for each parameter in the plan. See the parameters section for formatting guidelines. For example:

   # @summary A simple plan.
   #
   # @param param1
   #   First parameter description.
   # @param param2
   #   Second parameter description.
   # @param param3
   #   Third parameter description.
   plan mymodule::my_plan(String $param1, $param2, Integer $param3 = 1) {
     run_task('mymodule::lb_remove', $param1, target => $param2)
   }