puppet-strings 0.99.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a6a68c372004eb1cf650ae8542c16dd019614ec1
-  data.tar.gz: b4e29585c10fa54c4ad5a141a0c04ac22f642739
+  metadata.gz: 2beba5e6c9153efb0208b8dd2fe19eb0ae1ea589
+  data.tar.gz: f64ddfa0a74a5aeef8e525cbb59512888dd6bc2f
 SHA512:
-  metadata.gz: 8e2d046b43f397bd7f6580e7312edb4f1a7e58de320927af653bcf2c0f830b4260a0473616c8817f98561cf38ea997951ebe96b1697e4507a3041546168a9d28
-  data.tar.gz: c5828dc16270f1e2a51f77ff2be199c322b2c5d7e95eb72178bf9151998b0e804ac1efde40e22c279f3541b1e3fb50c11fa7b2c43c2bbcd54c07169f4cf71385
+  metadata.gz: 144215672c483f72a13b23897613fdf7440e6c6ce4d4310b407d7192a889037e58a1bc38a4a9d40b3fbf121c91bde7ccca2e126a374e91828a768c8a69b04405
+  data.tar.gz: 1e3525e0d4689fee040d12c9dac44f6184803d49327aa6707d18d64d641543deea47e526adf38c5a3af2dab4da6c1e46f86612c52fe747bbadabd4a71102b7e6

data/CHANGELOG.md

@@ -1,3 +1,26 @@
+##2016-11-28 - Release 1.0.0
+
+###Summary
+
+This release fixes up minor bugs from the 0.99.0 release and modifies the JSON schema for Puppet functions.
+
+All related tickets can be found under the [PDOC](https://tickets.puppetlabs.com/browse/PDOC) JIRA project with the fix version of [1.0.0](https://tickets.puppetlabs.com/issues/?filter=23607).
+
+###Features
+- The JSON schema for Puppet functions has been altered to include a new 'signatures' top-level key **(PDOC-125)**
+  - Includes information about all function signatures (overloads). Existing overload key format has been preserved.
+- Reworked README for enhanced clarity **(PDOC-133)**
+
+###BugFixes
+- Fixed an issue where the search box in the code navigator overlapped list items below it **(PDOC-93)**
+- Strings can now handle multiple `defaultfor` calls in Puppet providers **(PDOC-95)**
+- Fixed an issue preventing the generated \_index.html file from being uploaded to GitHub pages via the gh_pages task **(PDOC-120)**
+- Fixed several issues with String's handling of Puppet 3.x and 4.x function return types **(PDOC-135)**, **(PDOC-136)**
+- Fixed an issue where String's didn't properly parse overloads if no summary description was provided **(PDOC-129)**
+- Strings now correctly handles Puppet 3.x functions when the `newfunction` call is on a newline **(PDOC-122)**
+- Fixed an issue where certain Ruby string constructs were incompletely stripped from some docstrings **(PDOC-126)**
+- Hanging indents from type feature descriptions are now properly stripped **(PDOC-127)**
+
 ##2016-10-10 - Release 0.99.0
 
 ###Summary

data/Gemfile

@@ -6,12 +6,10 @@ gem 'rgen'
 gem 'redcarpet'
 gem 'yard', '~> 0.9.5'
 
-puppetversion = ENV['PUPPET_VERSION']
-
-if puppetversion
-  gem 'puppet', puppetversion
+if ENV['PUPPET_GEM_VERSION']
+  gem 'puppet', ENV['PUPPET_GEM_VERSION'], :require => false
 else
-  gem 'puppet'
+  gem 'puppet', :require => false
 end
 
 group :test do
@@ -19,7 +17,6 @@ group :test do
   gem 'mocha'
   gem 'puppetlabs_spec_helper'
   gem 'serverspec'
-  gem 'rubocop', '~> 0.41.0'
 end
 
 group :acceptance do
@@ -36,3 +33,7 @@ group :development do
     gem 'pry-byebug'
   end
 end
+
+gem 'json',      '<= 1.8'   if RUBY_VERSION < '2.0.0'
+gem 'json_pure', '<= 2.0.1' if RUBY_VERSION < '2.0.0'
+gem 'rubocop'               if RUBY_VERSION >= '2.0.0'

data/JSON.md

@@ -3,7 +3,7 @@ Puppet Strings JSON Data
 
 Puppet Strings has two flags to the `generate` action that can be used to emit JSON data:
 
-* `--emit-json <file>`: Emits the JSON data to the given file. 
+* `--emit-json <file>`: Emits the JSON data to the given file.
 * `--emit-json-stdout`: Emits the JSON data to STDOUT.
 
 Document Schema
@@ -100,13 +100,13 @@ Each entry in the `providers` list is an object with the following attributes:
 | Attribute Key | Description                                          |
 | ------------- | ---------------------------------------------------- |
 | name          | The name of the provider.                            |
-| type_name     | The name of the resource type of the provider.       | 
+| type_name     | The name of the resource type of the provider.       |
 | file          | The file defining the provider.                      |
 | line          | The line where the provider is defined.              |
 | docstring     | The *DocString* object for the provider (see below). |
 | confines      | The string map of confines for the provider.         |
 | features      | The list of features implemented by the provider.    |
-| defaults      | The string map of "default for" for the provider.    |
+| defaults      | The list of lists of "default for" for the provider. |
 | commands      | The string map of commands for the provider.         |
 
 Puppet Functions
@@ -114,23 +114,38 @@ Puppet Functions
 
 Each entry in the `puppet_functions` list is an object with the following attributes:
 
-| Attribute Key | Description                                          |
-| ------------- | ---------------------------------------------------- |
-| name          | The name of the function.                            |
-| file          | The file defining the provider.                      |
-| line          | The line where the provider is defined.              |
-| type          | The function type (e.g. ruby3x, ruby4x, puppet).     |
-| signature     | The Puppet signature of the function (no overloads). |
-| docstring     | The *DocString* object for the function (see below). |
-| defaults      | The map of parameter names to default values.        |
-| source        | The source code for the function.                    |
+| Attribute Key | Description                                                                   |
+| ------------- | ----------------------------------------------------------------------------- |
+| name          | The name of the function.                                                     |
+| file          | The file defining the provider.                                               |
+| line          | The line where the provider is defined.                                       |
+| type          | The function type (e.g. ruby3x, ruby4x, puppet).                              |
+| signatures    | A list of Puppet signatures of the function, including overloads if present.  |
+| docstring     | The *DocString* object for the function (see below).                          |
+| defaults      | The map of parameter names to default values.                                 |
+| source        | The source code for the function.                                             |
+
+Signature Objects
+-----------------
+
+The `signatures` key is a function-specific list containing an object for each signature of a
+function. Each object includes the `signature` itself, as well as each of its `param` and `return`
+tags. Puppet 4.x functions with overloads will contain multiple signatures, while other function
+types will contain only one.
+
+Each signature is represented as an object with the following attributes:
+
+| Attribute Key | Description                                                                                        |
+| ------------- | -------------------------------------------------------------------------------------------------- |
+| signature     | The signature of the function.                                                                     |
+| docstring     | The *DocString* object describing the signature, which includes `text`, `param` and `return` tags. |
 
 DocString Objects
 -----------------
 
 For the above types, their docstrings are represented as an object with the following attributes:
 
-| Attribute Key | Description                                       DocString  |
+| Attribute Key | Description                                         |
 | ------------- | --------------------------------------------------- |
 | text          | The textual part of the DocString.                  |
 | tags          | The array of tag objects, if any are present.       |
@@ -327,9 +342,24 @@ An example JSON document describing a Puppet class, defined type, resource type,
         "implements_some_feature",
         "some_other_feature"
       ],
-      "defaults": {
-        "kernel": "Linux"
-      },
+      "defaults": [
+        [
+          [
+            "kernel",
+            "Linux"
+          ]
+        ],
+        [
+          [
+            "osfamily",
+            "RedHat",
+          ],
+          [
+            "operatingsystemmajrelease",
+            "7"
+          ]
+        ]
+      ],
       "commands": {
         "foo": "/usr/bin/foo"
       }
@@ -341,7 +371,47 @@ An example JSON document describing a Puppet class, defined type, resource type,
       "file": "site.pp",
       "line": 20,
       "type": "puppet",
-      "signature": "func(Integer $param1, Any $param2, String $param3 = hi)",
+      "signatures": [
+        {
+          "signature": "func(Integer $param1, Any $param2, String $param3 = hi)",
+          "docstring": {
+            "text": "A simple function.",
+            "tags": [
+              {
+                "tag_name": "param",
+                "text": "First param.",
+                "types": [
+                  "Integer"
+                ],
+                "name": "param1"
+              },
+              {
+                "tag_name": "param",
+                "text": "Second param.",
+                "types": [
+                  "Any"
+                ],
+                "name": "param2"
+              },
+              {
+                "tag_name": "param",
+                "text": "Third param.",
+                "types": [
+                  "String"
+                ],
+                "name": "param3"
+              },
+              {
+                "tag_name": "return",
+                "text": "Returns nothing.",
+                "types": [
+                  "Undef"
+                ]
+              }
+            ]
+          }
+        }
+      ],
       "docstring": {
         "text": "A simple function.",
         "tags": [
@@ -388,7 +458,39 @@ An example JSON document describing a Puppet class, defined type, resource type,
       "file": "func3x.rb",
       "line": 1,
       "type": "ruby3x",
-      "signature": "func3x(String $first, Any $second)",
+      "signatures": [
+        {
+          "signature": "func3x(String $first, Any $second)",
+          "docstring": {
+            "text": "An example 3.x function.",
+            "tags": [
+              {
+                "tag_name": "param",
+                "text": "The first parameter.",
+                "types": [
+                  "String"
+                ],
+                "name": "first"
+              },
+              {
+                "tag_name": "param",
+                "text": "The second parameter.",
+                "types": [
+                  "Any"
+                ],
+                "name": "second"
+              },
+              {
+                "tag_name": "return",
+                "text": "Returns nothing.",
+                "types": [
+                  "Undef"
+                ]
+              }
+            ]
+          }
+        }
+      ],
       "docstring": {
         "text": "An example 3.x function.",
         "tags": [
@@ -424,6 +526,78 @@ An example JSON document describing a Puppet class, defined type, resource type,
       "file": "func4x.rb",
       "line": 11,
       "type": "ruby4x",
+      "signatures": [
+        {
+          "signature": "func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)",
+          "docstring": {
+            "text": "The first overload.",
+            "tags": [
+              {
+                "tag_name": "param",
+                "text": "The first parameter.",
+                "types": [
+                  "Integer"
+                ],
+                "name": "param1"
+              },
+              {
+                "tag_name": "param",
+                "text": "The second parameter.",
+                "types": [
+                  "Any"
+                ],
+                "name": "param2"
+              },
+              {
+                "tag_name": "param",
+                "text": "The third parameter.",
+                "types": [
+                  "Optional[Array[String]]"
+                ],
+                "name": "param3"
+              },
+              {
+                "tag_name": "return",
+                "text": "Returns nothing.",
+                "types": [
+                  "Undef"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "signature": "func4x(Boolean $param, Callable &$block)",
+          "docstring": {
+            "text": "The second overload.",
+            "tags": [
+              {
+                "tag_name": "param",
+                "text": "The first parameter.",
+                "types": [
+                  "Boolean"
+                ],
+                "name": "param"
+              },
+              {
+                "tag_name": "param",
+                "text": "The block parameter.",
+                "types": [
+                  "Callable"
+                ],
+                "name": "&block"
+              },
+              {
+                "tag_name": "return",
+                "text": "Returns a string.",
+                "types": [
+                  "String"
+                ]
+              }
+            ]
+          }
+        }
+      ],
       "docstring": {
         "text": "An example 4.x function.",
         "tags": [
@@ -508,4 +682,3 @@ An example JSON document describing a Puppet class, defined type, resource type,
   ]
 }
 ```
-

data/README.md

@@ -6,8 +6,6 @@ A Puppet command built on [YARD](http://yardoc.org/).
 
 Puppet Strings generates HTML documentation for Puppet extensions written in Puppet and Ruby.
 
-This tool will eventually place the existing `puppet doc` command once feature parity has been achieved.
- 
 |                |                                                                 |
 | -------------- |---------------------------------------------------------------- |
 | *Code*         | [GitHub][repo]                                                  |
@@ -23,123 +21,155 @@ This tool will eventually place the existing `puppet doc` command once feature p
 [contributing]: https://github.com/puppetlabs/puppet-strings/blob/master/CONTRIBUTING.md
 [committers]: https://github.com/puppetlabs/puppet-strings/blob/master/COMMITTERS.md
 
-Requirements
-------------
+## Installing Puppet Strings
+
+### Requirements
 
-In order to run strings you need to have the following software installed:
+To run Strings, you need the following software:
 
   * Ruby 1.9.3 or newer
   * Puppet 3.7 or newer
   * The `yard` Ruby gem
 
-Note that a few extra steps are necessary to install puppet-strings with Puppet Enterprise 3.8.
+Note that if you are running PE 3.8, you'll have a few extra steps to install puppet-strings.
 
-Installing the YARD Gem
------------------------
+### 1. Install the YARD Gem
 
 The easiest way to install the `yard` gem is with Puppet itself:
 
-For Puppet 4.x:
+For Puppet 4.x and Puppet Enterprise 2015.2 and later:
+
 ```
 $ puppet resource package yard provider=puppet_gem
 ```
 
 For Puppet 3.x:
+
 ```
 $ puppet resource package yard provider=gem
 ```
 
 For Puppet Enterprise 3.8:
+
 ```
 GEM_HOME=/opt/puppet/lib/ruby/gems/1.9.1 puppet resource package yard provider=gem
 ```
 
-Installing the redcarpet Gem (Puppet Enterprise 3.8 only)
--------------------------
+### 2. Puppet Enterprise 3.8 only: Install the redcarpet gem
+
 ```
 GEM_HOME=/opt/puppet/lib/ruby/gems/1.9.1 puppet resource package redcarpet provider=gem
 ```
 
-Installing Puppet Strings
--------------------------
+### 3. Install Puppet Strings
 
-Strings can be installed using the [puppet-strings](https://rubygems.org/gems/puppet-strings) gem.
+Install the [puppet-strings](https://rubygems.org/gems/puppet-strings) gem. To ensure that Strings is installed in the right place, install the gem with Puppet as shown below.
 
-To ensure it is installed in right place, it is best to install it using Puppet:
+For Puppet 4.x and Puppet Enterprise 2015.2 and later:
 
-For Puppet 4.x:
 ```
 $ puppet resource package puppet-strings provider=puppet_gem
 ```
 
 For Puppet 3.x:
+
 ```
 $ puppet resource package puppet-strings provider=gem
 ```
 
 For Puppet Enterprise 3.8:
+
 ```
 GEM_HOME=/opt/puppet/lib/ruby/gems/1.9.1 puppet resource package puppet-strings provider=gem
 ```
 
-Running Puppet Strings
-----------------------
+### 4. Optional: Set YARD options for Strings
 
-Once strings has been installed you can document a puppet module:
+Puppet Strings supports YARD options (on the command line, run `yard help doc` for a list of possible options. To set YARD options, specify a `yardopts` file in the same directory in which you run `puppet strings`. 
 
-```
-$ cd /path/to/module
-$ puppet strings
-```
+Puppet Strings supports the Markdown format and automatically sets the YARD `markup` option to `markdown`.
+
+## Generating documentation with Puppet Strings
+
+The `puppet strings` command processes the `README` file, as well as all Puppet and Ruby source files under the `./manifests/`, `./functions/`, and `./lib/`
+directories, and then creates HTML documentation under the `./doc/` directory.
+
+### Generate module documentation
 
-This processes `README` and all Puppet and Ruby source files under the `./manifests/`, `./functions/`, and `./lib/`
-directories by default and creates HTML documentation under the `./doc/` directory.
+To generate documentation for a Puppet module, run Strings from that module's directory. 
 
-To document specific files:
+1. Change directory into the module: `cd /modules/sample-module`.
+2. Run the command: `puppet strings`.
+
+### Generate documentation for specific files
+
+To generate documentation for specific files in a module, run the `puppet strings generate` subcommand and specify the files. 
 
 ```
-$ puppet strings generate first.pp second.pp ...
+puppet strings generate first.pp second.pp`
 ```
 
-To document specific directories:
+To generate documentation for specific directories, run the `puppet strings generate` command and specify the directories:
 
 ```
 $ puppet strings generate 'modules/foo/lib/**/*.rb' 'modules/foo/manifests/**/*.pp' 'modules/foo/functions/**/*.pp' ...
 ```
 
-Strings can emit JSON documenting the Puppet extensions:
+### Set additional options for document generation
+
+If you need to specify additional options when generating documentation, use the `puppet strings:generate` rake task. This command behaves exactly as `puppet strings generate`, but allows you to add the following parameters:
+
+* `patterns`: the search patterns to use for finding files to document (defaults to `manifests/**/*.pp functions/**/*.pp types/**/*.pp lib/**/*.rb`).
+* `debug`: enables debug output when set to `true`.
+* `backtrace`: enables backtraces for errors when set to `true`.
+* `markup`: the markup language to use (defaults to `markdown`).
+* `yard_args`: additional arguments to pass to YARD.
+
+For setup and usage details for the `puppet strings:generate` task, see [Rake tasks](#rake-tasks).
+
+## Viewing generated documentation
+
+Strings generates documentation as HTML in a `./doc/` directory within the module for which you are generating documentation. Strings can also serve the generated docs locally or output documentation in JSON.
+
+### Serve documents locally
+
+Strings can serve the generated HTML documentation with the `server` action. This action serves documentation for all modules in the [module path](https://docs.puppet.com/puppet/latest/reference/dirs_modulepath.html) at `http://localhost:8808`.
+
+To serve documentation locally, run:
 
 ```
-$ puppet strings generate --emit-json documentation.json
+$ puppet strings server
 ```
 
-It can also print the JSON to stdout:
+### Output documents in JSON
+
+Strings can produce documentation in JSON and then either generate a `.json` file or print JSON to stdout. This can be useful for handling or displaying the data with your own custom applications.
+
+To generate JSON documentation to a file, run:
 
 ```
-$ puppet strings generate --emit-json-stdout
+$ puppet strings generate --emit-json documentation.json
 ```
 
-The schema for the JSON output is [documented here](https://github.com/puppetlabs/puppet-strings/blob/master/JSON.md).
-
-In addition to generating a directory full of HTML, you can also serve up documentation for all your modules using the `server` action:
+To generate and then print JSON documentation to stdout, run:
 
 ```
-$ puppet strings server
+$ puppet strings generate --emit-json-stdout
 ```
 
-YARD Options
-------------
+For details about Strings JSON output, see [Strings JSON schema](https://github.com/puppetlabs/puppet-strings/blob/master/JSON.md).
 
-YARD options (see `yard help doc`) are supported in a `.yardopts` file in the same directory where `puppet strings` is run.
+### Output documents to GitHub Pages
 
-Puppet Strings automatically sets the `markup` option to `markdown`, allowing your documentation strings to be in Markdown format.
+To generate documents and then make them available on [GitHub Pages](https://pages.github.com/), use the Strings rake task `strings:gh_pages:update`. See [Rake tasks](#rake-tasks) for setup and usage details.
 
-Documenting Puppet Extensions
------------------------------
+## Documenting Puppet code for Strings
 
-### Puppet Classes / Defined Types
+Strings relies on code comments and YARD docstrings to specify documentation comments. Comments can include free-form text that is treated as a high-level overview for the element being documented. You can also include any number of YARD tags that hold semantic metadata for various aspects of the code. These tags allow you to add this data to the code without worrying about presentation.
 
-To document Puppet classes and defined types, use a YARD docstring before the class or defined type definition:
+### Documenting Puppet classes and defined types
+
+To document Puppet classes and defined types, use a series of comments to create a YARD docstring before the class or defined type definition.
 
 ```puppet
 # An example class.
@@ -157,8 +187,27 @@ class example_class(
 ) inherits example::params {
   # ...
 }
+```
 
-# An example defined type.
+The Strings elements appearing in the above comment block are:
+
+* Three comment lines, not prefixed with tags, give the class description.
+* The `@example` YARD tag, immediately followed by an optional title.
+* The `include` statement, which adds the usage example code.
+* Two `@param` tags, with the name of the parameter first, followed by a string describing the parameter's purpose.
+
+Puppet 4 is a typed language, so Puppet Strings automatically documents the parameter types from code. With Puppet 3, however, include the parameter type with the `@param` tag:
+
+```
+# @param [String] first The first parameter for this class.
+# @param [Integer] second The second parameter for this class.
+```
+
+Note that if you document a parameter's type, and that parameter already has a Puppet type specifier, Strings emits a warning.
+
+Defined types are documented in exactly the same way as classes:
+
+```
 #
 # This is an example of how to document a defined type.
 # @param ports The array of port numbers to use.
@@ -169,12 +218,9 @@ define example_type(
 }
 ```
 
-***Note: unlike Ruby, Puppet 4.x is a typed language; Puppet Strings will automatically use the parameter type information to 
-document the parameter types.  A warning will be emitted if you document a parameter's type for a parameter that has a Puppet type specifier.***
-
-### Resource Types
+### Documenting resource types and providers
 
-To document custom resource types and their parameters/properties, use the `desc` method or assign a value to the `doc` attribute:
+To document resource types, pass descriptions for each parameter, property, and the resource type itself to the `desc` method. Each description can include other tags as well, including examples.
 
 ```ruby
 Puppet::Type.newtype(:example) do
@@ -185,27 +231,22 @@ An example resource type.
     param => 'hi'
   }
 DESC
-  
+
   newparam(:param) do
     desc 'An example parameter.'
     # ...
   end
-  
+
   newproperty(:prop) do
     desc 'An example property.'
     #...
   end
-   
+
   # ...  
 end
 ```
-
-Puppet Strings documents this way to preserve backwards compatibility with `puppet doc` and existing resource types.
-
-***Note: Puppet Strings does not evaluate your Ruby code, so only certain static expressions are supported.***
-
-To document parameters and properties that are dynamically created, use the `#@!puppet.type.param` and `#@!puppet.type.property`
-directives before the `newtype` call:
+ 
+If your resource type includes dynamically created parameters and properties, you must also use the `#@!puppet.type.param` and `#@!puppet.type.property` directives **before** the `newtype` call. This is necessary because Strings does not evaluate Ruby code, so it cannot detect dynamic attributes.
 
 ```ruby
 # @!puppet.type.param [value1, value2, value3] my_param Documentation for a dynamic parameter.
@@ -215,51 +256,27 @@ Puppet::Type.newtype(:example) do
 end
 ```
 
-### Providers
-
-To document providers, use the `desc` method or assign a value to the `doc` attribute:
+Document providers similarly, again using the `desc` method:
 
 ```ruby
 Puppet::Type.type(:example).provide :platform do
   desc 'An example provider.'
-  
+
   # ...
 end
 ```
 
-Puppet Strings documents this way to preserve backwards compatibility with `puppet doc` and existing resource types.
+All provider method calls, including `confine`, `defaultfor`, and `commands`, are automatically parsed and documented by Strings. The `desc` method is used to generate the docstring, and can include tags such as `@example` if written as a heredoc.
 
-***Note: Puppet Strings does not evaluate your Ruby code, so only certain static expressions are supported.***
+**Note**: Puppet Strings can not evaluate your Ruby code, so only certain static expressions are supported.
 
-### Functions
+### Documenting functions
 
-Puppet Strings supports three different ways of defining a function in Puppet: with the Puppet 3.x API, Puppet 4.X API,
-and in the Puppet language itself.
+Puppet Strings supports the documenting of defined functions with the Puppet 4 API, the Puppet 3 API, or in the Puppet language itself.
 
-#### Puppet 3.x Functions
+#### Document Puppet 4 functions
 
-To document a function in the Puppet 3.x API, use the `doc` option to `newfunction`:
-
-```ruby
-Puppet::Parser::Functions.newfunction(:example, doc: <<-DOC
-Documentation for an example 3.x function.
-@param [String] param1 The first parameter.
-@param [Integer] param2 The second parameter.
-@return [Undef]
-@example Calling the function.
-  example('hi', 10)
-DOC
-) do |*args|
-  #...
-end
-```
-
-***Note: if parameter types are omitted, a default of the `Any` Puppet type will be used.***
-
-#### Puppet 4.x Functions
-
-To document a function in the Puppet 4.x API, use a YARD docstring before the `create_function` call and any `dispatch`
-calls:
+To document a function in the Puppet 4 API, use a YARD docstring before the `create_function` call and before any `dispatch` calls:
 
 ```ruby
 # An example 4.x function.
@@ -273,16 +290,14 @@ Puppet::Functions.create_function(:example) do
     param 'String', :first
     param 'Integer', :second
   end
-  
+
   # ...
 end
 ```
 
-***Note: Puppet Strings will automatically use the parameter type information from the `dispatch` block to document 
-the parameter types. Only document your parameter types when the Puppet 4.x function contains no `dispatch` calls.***
+**Note**: Puppet Strings automatically uses the parameter type information from the `dispatch` block to document the parameter types. Only document your parameter types when the Puppet 4.x function contains no `dispatch` calls.
 
-If the Puppet 4.x function contains multiple `dispatch` calls, Puppet Strings will automatically create `overload` tags
-to describe the function's overloads:
+If the Puppet 4 function contains multiple `dispatch` calls, Puppet Strings automatically creates `overload` tags to describe the function's overloads:
 
 ```ruby
 # An example 4.x function.
@@ -295,7 +310,7 @@ Puppet::Functions.create_function(:example) do
   dispatch :example_string do
     param 'String', :first
   end
-  
+
   # Overload by integer.
   # @param first The first parameter.
   # @return [Integer] Returns an integer.
@@ -304,13 +319,33 @@ Puppet::Functions.create_function(:example) do
   dispatch :example_integer do
     param 'Integer', :first
   end
-  
+
   # ...
 ```
 
-The resulting HTML for this example function will document both `example(String $first)` and `example(Integer $first)`. 
+The resulting HTML for this example function documents both `example(String $first)` and `example(Integer $first)`.
+
+#### Document Puppet 3 functions
+
+To document a function in the Puppet 3 API, use the `doc` option to `newfunction`:
+
+```ruby
+Puppet::Parser::Functions.newfunction(:example, doc: <<-DOC
+Documentation for an example 3.x function.
+@param [String] param1 The first parameter.
+@param [Integer] param2 The second parameter.
+@return [Undef]
+@example Calling the function.
+  example('hi', 10)
+DOC
+) do |*args|
+  #...
+end
+```
+
+Because Puppet 3 is not typed in the way Puppet 4 is, specify the type for each parameter (for example, `@param [String]` for a string parameter). If a parameter type is omitted, a default of the `Any` Puppet type will be used.
 
-#### Puppet Language Functions
+#### Document Puppet language functions
 
 To document Puppet functions written in the Puppet language, use a YARD docstring before the function definition:
 
@@ -325,42 +360,90 @@ function example(String $name) {
 }
 ```
 
-***Note: Puppet Strings will automatically use the parameter type information from the function's parameter list to document 
-the parameter types.***
+**Note**: Puppet Strings automatically uses the parameter type information from the function's parameter list to document the parameter types.
 
-Additional Resources
---------------------
+### Including examples in documentation
 
-Here are a few other good resources for getting started with documentation:
+The `@example` YARD tag adds usage examples to any Ruby or Puppet language code.
 
-  * [Module README Template](https://docs.puppet.com/puppet/latest/reference/modules_documentation.html)
-  * [YARD Getting Started Guide](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md)
-  * [YARD Tags Overview](http://www.rubydoc.info/gems/yard/file/docs/Tags.md)
+```puppet
+# @example String describing what this example demonstrates.
+#   $content = example('world')
+#   if $content == 'world' {
+#     include world
+#   }
+function example(string $name) {
+  "hello $name"
+}
+```
 
-Rake Tasks
-----------
+The string following the `@example` tag is an optional title which is displayed prominently above the code block.
 
-Puppet Strings comes with two rake tasks: `strings:generate` and `strings:gh_pages:update` available in `puppet-strings/tasks`.
+The example body must begin on a newline underneath the tag, and each line of the example itself must be indented by
+at least one space. Further indentation is preserved as preformatted text in the generated documentation.
 
-Add the following to your Gemfile to use `puppet-strings`:
+### Including multi-line tag descriptions
 
-```ruby
-gem 'puppet-strings', :git => 'https://github.com/puppetlabs/puppet-strings.git'
+You can spread tag descriptions across multiple lines, similar to multi-line examples, as long as subsequent lines are each uniformly indented by at least one space.
+
+For example:
+
+```puppet
+# @param name The name the function uses to say hello. Note that this
+#   description is extra long, so we've broken it up onto newlines for the sake
+#   of readability.
+function example(string $name) {
+  "hello $name"
+}
 ```
 
-In your `Rakefile`, add the following to use the `puppet-strings` tasks:
+## Reference
 
-```ruby
+### Available Strings tags
+
+The most commonly used tags for Strings are:
+
+* `@param`: Documents a parameter with a given name, type and optional description.
+* `@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".
+* `@example`: Shows an example snippet of code for an object. The first line is an optional title. See above for more about how to [include examples in documentation](#including-examples-in-documentation).
+* `@!puppet.type.param`: Documents dynamic type parameters. See [Documenting resource types and providers](#documenting-resource-types-and-providers) above.
+* `@!puppet.type.property`: Documents dynamic type properties. See [Documenting resource types and providers](#documenting-resource-types-and-providers) above.
+* `@since`: Lists the version in which the object was first added.
+* `@see`: Adds "see also" references. Accepts URLs or other code objects with an optional description at the end. Note that the URL or object is automatically linked by YARD and does not need markup formatting.
+
+For a complete list of tags, see the [YARD Tags Overview](http://www.rubydoc.info/gems/yard/file/docs/Tags.md).
+
+### Rake tasks
+
+You can use Puppet Strings rake tasks to generate documentation with additional options or to make your generated docs available on [GitHub Pages](https://pages.github.com/).
+
+The `strings:generate` and `strings:gh_pages:update` tasks are available in `puppet-strings/tasks`.
+
+First, update your Gemfile and your Rakefile.:
+
+1. Add the following to your Gemfile to use `puppet-strings`:
+
+   ```ruby
+gem 'puppet-strings'
+   ```
+
+2. Add the following to your `Rakefile` to use the `puppet-strings` tasks:
+
+   ```ruby
 require 'puppet-strings/tasks'
-```
+   ```
+   
+   Adding this `require` automatically creates the Rake tasks below.
+
+#### Generate documentation with additional options
 
-The `strings:generate` task can be used to generate documentation:
+Use the `strings:generate` task to generate documentation:
 
 ```
 $ rake strings:generate
 ```
 
-The task accepts the following parameters:
+This command behaves exactly as `puppet strings generate`, but allows you to add the following parameters:
 
 * `patterns`: the search patterns to use for finding files to document (defaults to `manifests/**/*.pp functions/**/*.pp types/**/*.pp lib/**/*.rb`).
 * `debug`: enables debug output when set to `true`.
@@ -368,49 +451,57 @@ The task accepts the following parameters:
 * `markup`: the markup language to use (defaults to `markdown`).
 * `yard_args`: additional arguments to pass to YARD.
 
-An example of passing arguments to the `strings:generate` Rake task:
+For example, the task below adds a search pattern, debugs output, backtraces errors, sets the markup language to `markdown`, and passes an additional YARD argument setting the readme file to `README.md`:
 
 ```
 $ rake strings:generate\['**/*{.pp\,.rb}, true, true, markdown, --readme README.md']
 ```
 
-The `strings:gh_pages:update` task will generate your Puppet Strings documentation to be made available via [GitHub Pages](https://pages.github.com/). It will:
+#### Generate documentation on GitHub Pages
+
+To generate Puppet Strings documentation and make it available on [GitHub Pages](https://pages.github.com/), use the `strings:gh_pages:update` task.
+
+This task:
 
-1. Create a `doc` directory in the root of your project
-2. Check out the `gh-pages` branch of the current repository in the `doc` directory (it will create a branch if one does not already exist)
-3. Generate strings documentation using the `strings:generate` task
-4. Commit the changes and push them to the `gh-pages` branch **with the `--force` flag**
+1. Creates a `doc` directory in the root of your project.
+2. Checks out the `gh-pages` branch of the current repository in the `doc` directory (it creates a branch if one does not already exist).
+3. Generates Strings documentation with the `strings:generate` task.
+4. Commits the changes and pushes them to the `gh-pages` branch **with the `--force` flag**.
 
 This task aims to keep the `gh-pages` branch up to date with the current code and uses the `-f` flag when pushing to the `gh-pages` branch.
-***Please note this operation will be destructive if not used properly.***
 
-Developing and Contributing
----------------------------
+**Please note this operation is destructive if not used properly.**
+
+### Additional Resources
+
+Here are a few other good resources for getting started with documentation:
+
+  * [Module README Template](https://docs.puppet.com/puppet/latest/reference/modules_documentation.html)
+  * [YARD Getting Started Guide](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md)
+  * [YARD Tags Overview](http://www.rubydoc.info/gems/yard/file/docs/Tags.md)
+
+## Developing and Contributing
 
 We love contributions from the community!
 
-If you'd like to contribute to the strings module, check out [CONTRIBUTING.md](https://github.com/puppetlabs/puppet-strings/blob/master/CONTRIBUTING.md) to get information on the contribution process.
+If you'd like to contribute to puppet-strings, check out [CONTRIBUTING.md](https://github.com/puppetlabs/puppet-strings/blob/master/CONTRIBUTING.md) to get information on the contribution process.
 
-Running Specs
--------------
+### Running Specs
 
 If you plan on developing features or fixing bugs in Puppet Strings, it is essential that you run specs before opening a pull request.
 
-To run specs, simply execute the `spec` rake task:
+To run specs, run the `spec` rake task:
 
     $ bundle install --path .bundle/gems
     $ bundle exec rake spec
 
-Support
--------
+## Support
 
-Please log tickets and issues at our [JIRA tracker][JIRA]. A [mailing list](https://groups.google.com/forum/?fromgroups#!forum/puppet-users)
-is available for asking questions and getting help from others.
+Please log tickets and issues in our [JIRA tracker][JIRA]. A [mailing list](https://groups.google.com/forum/?fromgroups#!forum/puppet-users) is available for asking questions and getting help from others.
 
 There is also an active #puppet channel on the Freenode IRC network.
 
-We use semantic version numbers for our releases, and recommend that users stay as up-to-date as possible by upgrading to
+We use semantic version numbers for our releases and recommend that users upgrade to
 patch releases and minor releases as they become available.
 
-Bug fixes and ongoing development will occur in minor releases for the current major version.
-Security fixes will be ported to a previous major version on a best-effort basis, until the previous major version is no longer maintained.
+Bug fixes and ongoing development will occur in minor releases for the current major version. Security fixes will be ported to a previous major version on a best-effort basis, until the previous major version is no longer maintained.