Documenting modules with Puppet Strings

puppet strings [--generate] [--server]

puppet strings generate [--format <FORMAT>][--out <DESTINATION>] [<ARGUMENTS>]

puppet strings generate --format markdown --out docs/info.md

puppet strings generate manifest1.pp manifest2.pp

puppet strings server --modulepath path/to/modules

puppet strings server concat

@author

List the author or authors of a class, module, or method.

# @author Foo Bar
class MyClass; end

@api

Describes the resource as belonging to the private or public API. To mark a module element, such as a class, as private, specify as private:

# @api private

@example

Shows an example snippet of code for an object. The first line is an optional title, and any subsequent lines are automatically formatted as a code snippet. Use for specific examples of a given component. Use one example tag per example.

@param

Documents a parameter with a given name, type and optional description.

@!puppet.type.param

Documents dynamic type parameters. See the documenting resource types in the Strings style guide for detailed information.

@!puppet.type.property

Documents dynamic type properties. See the documenting resource types in the Strings style guide for detailed information.

@option

Used with a @param tag to defines what optional parameters the user can pass in an options hash to the method. For example:

  # @param [Hash] opts
  #      List of options
  # @option opts [String] :option1
  #      option 1 in the hash
  # @option opts [Array] :option2
  #      option 2 in the hash

@raise

Documents any exceptions that can be raised by the given component. For example:

 # @raise PuppetError this error is raised if x

@return

Describes the return value (and type or types) of a method. You can list multiple return tags for a method if the method has distinct return cases. In this case, begin each case with "if". For example:

# 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

@see

Adds "see also" references. Accepts URLs or other code objects with an optional description at the end. The URL or object is automatically linked by YARD and does not need markup formatting. Appears in the generated documentation as a "See Also" section. Use one tag per reference, such as a website or related method.

@since

Lists the version in which the object was first added. Strings does not verify that the specified version exists. You are responsible for providing accurate information.

@summary

A description of the documented item, of 140 characters or fewer.