puppet-strings 1.2.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 82ad70b526cc76afc1aa63fe94f18525f3a88ed5
-  data.tar.gz: 11c0250595f96c209f17625cdf7a8a41feee39c3
+  metadata.gz: 841114139c5e61cbe619f7d6282f08555a8cd890
+  data.tar.gz: 3acc7ea95bb3bdb7cf3890e3fb58d95f2d4f7e61
 SHA512:
-  metadata.gz: 55047d29045ebd5f26f52f0f26331b0b602d6d98c7e231b512052e87537664aba1f1b5c00613e07435d5b885683ba3a941941f382b104c3a89270cddbd836794
-  data.tar.gz: 71a37b237fd792a7c3c94acc72514068e24c87a75db75af5cd2f83196b7b100bbd9ab1682ccc54fb8b7d889412bfa806a75542a8cf77d0fc8d5ae87ae4d55803
+  metadata.gz: 7729f413ef4d94ecb2ada117ae4d93eabf096da95ad99804280121c33460466b76032f8c964abeafdf97d5ca38aed7ee551aac1dc77d3b07fcaf00bc46f1bb73
+  data.tar.gz: a4c6a1960fce2917d318acb4c6cd0f353779499acaf416dab177d3f2da7706f1475e0a7c694e4b58813faac7ebe48882937c89e3651ec67831a79bb43aac6cb5

data/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org).
 
+## [2.0.0](https://github.com/puppetlabs/puppet-strings/tree/2.0.0) (2018-05-11)
+
+[Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/1.2.1...2.0.0)
+
+### Changed
+
+- bump required ruby and puppet versions [\#178](https://github.com/puppetlabs/puppet-strings/pull/178) ([eputnam](https://github.com/eputnam))
+
+### Added
+
+- \(PDOC-238\) add generated message to markdown [\#175](https://github.com/puppetlabs/puppet-strings/pull/175) ([eputnam](https://github.com/eputnam))
+- \(PDOC-228\) puppet plan support [\#168](https://github.com/puppetlabs/puppet-strings/pull/168) ([eputnam](https://github.com/eputnam))
+- \(PDOC-206\) support for tasks [\#161](https://github.com/puppetlabs/puppet-strings/pull/161) ([eputnam](https://github.com/eputnam))
+
+### Fixed
+
+- \(PDOC-36\) fix hack for README urls [\#176](https://github.com/puppetlabs/puppet-strings/pull/176) ([eputnam](https://github.com/eputnam))
+- \(PDOC-240\) add handling for :array node type in rsapi\_handler [\#174](https://github.com/puppetlabs/puppet-strings/pull/174) ([eputnam](https://github.com/eputnam))
+- \(PDOC-159\) server urls fix [\#173](https://github.com/puppetlabs/puppet-strings/pull/173) ([eputnam](https://github.com/eputnam))
+- \(maint\) display Plans in markdown table of contents [\#171](https://github.com/puppetlabs/puppet-strings/pull/171) ([eputnam](https://github.com/eputnam))
+- \(PDOC-233\) markdown whitespace fixes [\#170](https://github.com/puppetlabs/puppet-strings/pull/170) ([JohnLyman](https://github.com/JohnLyman))
+- \(PDOC-229\) fix error with return\_type and @return [\#169](https://github.com/puppetlabs/puppet-strings/pull/169) ([eputnam](https://github.com/eputnam))
+- \(PDOC-36\) hack to fix README links in generated HTML [\#167](https://github.com/puppetlabs/puppet-strings/pull/167) ([eputnam](https://github.com/eputnam))
+- \(PDOC-192\) remove warning for title/name [\#166](https://github.com/puppetlabs/puppet-strings/pull/166) ([eputnam](https://github.com/eputnam))
+- \(maint\) add condition for misleading warning [\#155](https://github.com/puppetlabs/puppet-strings/pull/155) ([eputnam](https://github.com/eputnam))
+
 ## [1.2.1](https://github.com/puppetlabs/puppet-strings/tree/1.2.1) (2018-03-01)
 
 [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/1.2.0...1.2.1)

data/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # How to contribute
 
-Third-party patches are essential for keeping strings great. We want to keep it
+Third-party patches are essential for keeping Puppet Strings great. We want to keep it
 as easy as possible to contribute changes that get things working in your
 environment. There are a few guidelines that we need contributors to follow so
 that we can have a chance of keeping on top of things.
@@ -72,18 +72,14 @@ a ticket number.
 * Push your changes to a topic branch in your fork of the repository.
 * Submit a pull request to the repository in the puppetlabs organization.
 * Update your Jira ticket to mark that you have submitted code and are ready for it to be reviewed (Status: Ready for Merge).
-  * Include a link to the pull request in the ticket.
-* The core team looks at Pull Requests on a regular basis in a weekly triage
-  meeting that we hold in a public Google Hangout. The hangout is announced in
-  the weekly status updates that are sent to the puppet-dev list.
+* Include a link to the pull request in the ticket.
 * After feedback has been given we expect responses within two weeks. After two
   weeks will may close the pull request if it isn't showing any activity.
 
 # Additional Resources
 
 * [More information on contributing](http://links.puppet.com/contribute-to-puppet)
-* [Bug tracker (Jira)](http://tickets.puppetlabs.com)
+* [Bug tracker (Jira)](http://tickets.puppet.com)
 * [Contributor License Agreement](http://links.puppet.com/cla)
 * [General GitHub documentation](http://help.github.com/)
 * [GitHub pull request documentation](http://help.github.com/send-pull-requests/)
-* #puppet-dev IRC channel on freenode.org

data/JSON.md

@@ -1,15 +1,15 @@
 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-stdout`: Emits the JSON data to STDOUT.
+Puppet Strings can generate JSON to STDOUT with the `--format` option:
+```shell
+puppet strings generate --format json
+```
 
 Document Schema
 ===============
 
-At the top level, there are five arrays in the JSON document:
+At the top level, there are seven arrays in the JSON document:
 
 | Document Key     | Description                                                                   |
 | ---------------- | ----------------------------------------------------------------------------- |
@@ -17,7 +17,9 @@ At the top level, there are five arrays in the JSON document:
 | defined_types    | The list of defined types that were parsed.                                   |
 | resource_types   | The list of resource types that were parsed.                                  |
 | providers        | The list of resource providers that were parsed.                              |
-| puppet_functions | The list of Puppet functions (3.x, 4.x and Puppet language) that were parsed. |
+| puppet_functions | The list of Puppet functions (4.x, 4.x and Puppet language) that were parsed. |
+| puppet_tasks     | The list of Puppet tasks that were parsed.                                    |
+| puppet_plans     | The list of Puppet plans that were parsed.                                    |
 
 Puppet Classes
 --------------
@@ -117,14 +119,43 @@ Each entry in the `puppet_functions` list is an object with the following attrib
 | Attribute Key | Description                                                                   |
 | ------------- | ----------------------------------------------------------------------------- |
 | name          | The name of the function.                                                     |
-| file          | The file defining the provider.                                               |
-| line          | The line where the provider is defined.                                       |
+| file          | The file defining the function.                                               |
+| line          | The line where the function 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.                                             |
 
+Puppet Tasks
+------------
+
+Each entry in the `puppet_tasks` list is an object with the following attributes:
+
+| Attribute Key | Description                                                                   |
+| ------------- | ----------------------------------------------------------------------------- |
+| name          | The name of the task.                                                         |
+| file          | The file defining the task.                                                   |
+| line          | The line where the task is defined.                                           |
+| docstring     | The *DocString* object for the task (see below).                              |
+| source        | The source code for the task.                                                 |
+| supports_noop | Whether the task supports noop mode                                           |
+| input_method  | Maps to the `input_method` key in the task json                               |
+
+Puppet Plans
+------------
+
+Each entry in the `puppet_plans` list is an object with the following attributes:
+
+| Attribute Key | Description                                                                   |
+| ------------- | ----------------------------------------------------------------------------- |
+| name          | The name of the plan.                                                         |
+| file          | The file defining the plan.                                                   |
+| line          | The line where the plan is defined.                                           |
+| docstring     | The *DocString* object for the plan (see below).                              |
+| defaults      | The map of parameter names to default values.                                 |
+| source        | The source code for the plan.                                                 |
+
 Signature Objects
 -----------------
 
@@ -679,6 +710,93 @@ An example JSON document describing a Puppet class, defined type, resource type,
       },
       "source": "Puppet::Functions.create_function(:func4x) do\n  # The first overload.\n  # @param param1 The first parameter.\n  # @param param2 The second parameter.\n  # @param param3 The third parameter.\n  # @return [Undef] Returns nothing.\n  dispatch :foo do\n    param          'Integer',       :param1\n    param          'Any',           :param2\n    optional_param 'Array[String]', :param3\n  end\n\n  # The second overload.\n  # @param param The first parameter.\n  # @param block The block parameter.\n  # @return [String] Returns a string.\n  dispatch :other do\n    param 'Boolean', :param\n    block_param\n  end\nend"
     }
+  ],
+  "puppet_tasks": [
+    {
+      "name": "(stdin)",
+      "file": "(stdin)",
+      "line": 0,
+      "docstring": {
+        "text": "Allows you to backup your database to local file.",
+        "tags": [
+          {
+            "name": "database",
+            "tag_name": "param",
+            "text": "Database to connect to",
+            "types": [
+              "Optional[String[1]]"
+            ]
+          },
+          {
+            "name": "user",
+            "tag_name": "param",
+            "text": "The user",
+            "types": [
+              "Optional[String[1]]"
+            ]
+          },
+          {
+            "name": "password",
+            "tag_name": "param",
+            "text": "The password",
+            "types": [
+              "Optional[String[1]]"
+            ]
+          },
+          {
+            "name": "sql",
+            "tag_name": "param",
+            "text": "Path to file you want backup to",
+            "types": [
+              "String[1]"
+            ]
+          }
+        ]
+      },
+      "source": "{\n  \"description\": \"Allows you to backup your database to local file.\",\n  \"input_method\": \"stdin\",\n  \"parameters\": {\n    \"database\": {\n      \"description\": \"Database to connect to\",\n      \"type\": \"Optional[String[1]]\"\n    },\n    \"user\": {\n      \"description\": \"The user\",\n      \"type\": \"Optional[String[1]]\"\n    },\n    \"password\": {\n      \"description\": \"The password\",\n      \"type\": \"Optional[String[1]]\"\n    },\n     \"sql\": {\n      \"description\": \"Path to file you want backup to\",\n      \"type\": \"String[1]\"\n    }\n  }\n}\n",
+      "supports_noop": false,
+      "input_method": "stdin"
+    }
+  ],
+  "puppet_plans": [
+    {
+      "name": "plann",
+      "file": "(stdin)",
+      "line": 5,
+      "docstring": {
+        "text": "A simple plan.",
+        "tags": [
+          {
+            "tag_name": "param",
+            "text": "First param.",
+            "types": [
+              "String"
+            ],
+            "name": "param1"
+          },
+          {
+            "tag_name": "param",
+            "text": "Second param.",
+            "types": [
+              "Any"
+            ],
+            "name": "param2"
+          },
+          {
+            "tag_name": "param",
+            "text": "Third param.",
+            "types": [
+              "Integer"
+            ],
+            "name": "param3"
+          }
+        ]
+      },
+      "defaults": {
+        "param3": "1"
+      },
+      "source": "plan plann(String $param1, $param2, Integer $param3 = 1) {\n}"
+    }
   ]
 }
 ```

data/README.md

@@ -2,9 +2,8 @@ Puppet Strings
 ==============
 [![Build Status](https://travis-ci.org/puppetlabs/puppet-strings.png?branch=master)](https://travis-ci.org/puppetlabs/puppet-strings) [![Gem Version](https://badge.fury.io/rb/puppet-strings.svg)](https://badge.fury.io/rb/puppet-strings)
 
-A Puppet command built on [YARD](http://yardoc.org/).
+Puppet Strings generates documentation for Puppet code and extensions written in Puppet and Ruby. Strings processes code and YARD-style code comments to create documentation in HTML, Markdown, or JSON formats.
 
-Puppet Strings generates HTML documentation for Puppet extensions written in Puppet and Ruby.
 
 |                |                                                                 |
 | -------------- |---------------------------------------------------------------- |
@@ -25,512 +24,32 @@ Puppet Strings generates HTML documentation for Puppet extensions written in Pup
 
 ### Requirements
 
-To run Strings, you need the following software:
-
-  * Ruby 1.9.3 or newer
-  * Puppet 3.7 or newer
+  * Ruby 2.1.9 or newer
+  * Puppet 4.0 or newer
   * The `yard` Ruby gem
 
-Note that if you are running PE 3.8, you'll have a few extra steps to install puppet-strings.
-
-### 1. Install the YARD Gem
-
-The easiest way to install the `yard` gem is with Puppet itself:
-
-For Puppet >= 4 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 (Linux):
-
-```
-GEM_HOME=/opt/puppet/lib/ruby/gems/1.9.1 puppet resource package yard provider=gem
-```
-
-For Puppet Enterprise 3.8 (Windows):
-
-```
-$env:GEM_HOME = "C:\Program Files\Puppet Labs\Puppet Enterprise\sys\ruby\lib\ruby\gems\2.0.0"
-puppet resource package yard provider=gem
-```
-
-### 2. Puppet Enterprise 3.8 in Linux only: Install the redcarpet gem
-
-```
-GEM_HOME=/opt/puppet/lib/ruby/gems/1.9.1 puppet resource package redcarpet provider=gem
-```
+### Install Puppet Strings
 
-### 3. Install Puppet Strings
+1. Install the YARD gem by running `gem install yard`
+1. Install the `puppet-strings` gem by running `gem install puppet-strings`
+1. **Optional**: Set YARD options for Strings
 
-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 use YARD options with Puppet Strings, specify a `yardopts` file in the same directory in which you run `puppet strings`. Puppet Strings supports the Markdown format and automatically sets the YARD `markup` option to `markdown`.
 
-For Puppet 4.x and Puppet Enterprise 2015.2 and later:
+   To see a list of available YARD options, run `yard help doc`. For details about YARD options configuration, see the [YARD docs](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md#config).
 
-```
-$ puppet resource package puppet-strings provider=puppet_gem
-```
-
-For Puppet 3.x:
-
-```
-$ puppet resource package puppet-strings provider=gem
-```
-
-For Puppet Enterprise 3.8 (Linux):
-
-```
-GEM_HOME=/opt/puppet/lib/ruby/gems/1.9.1 puppet resource package puppet-strings provider=gem
-```
-
-For Puppet Enterprise 3.8 (Windows)
-
-```
-$env:GEM_HOME = "C:\Program Files\Puppet Labs\Puppet Enterprise\sys\ruby\lib\ruby\gems\2.0.0"
-puppet resource package puppet-strings provider=gem
-```
-
-### 4. Optional: Set YARD options for Strings
-
-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`. 
-
-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
-
-To generate documentation for a Puppet module, run Strings from that module's directory. 
-
-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
-```
-
-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' ...
-```
-
-### 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 server
-```
-
-### 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 --format json --out documentation.json
-```
-
-To generate and then print JSON documentation to stdout, run:
-
-```
-$ puppet strings generate --format json
-```
-
-For details about Strings JSON output, see [Strings JSON schema](https://github.com/puppetlabs/puppet-strings/blob/master/JSON.md).
-
-### Output documents in Markdown
-
-Strings can also produce documentation in Markdown and then either generate an `.md` file or print Markdown to stdout. The generated markdown layout has been reviewed and approved by Puppet's tech pubs team and is the same that is used in Puppet Supported modules.
-
-To generate REFERENCE.md:
-
-```
-$ puppet strings generate --format markdown
-```
-
-To write Markdown documentation to another file, use the --out option:
-
-```
-$ puppet strings generate --format markdown --out docs/INFO.md
-```
-
-### Output documents to GitHub Pages
-
-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 code for Strings
-
-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.
-
-### 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.
-#
-# This is an example of how to document a Puppet class
-#
-# @summary A short summary of the purpose of the class.
-#
-# @example Declaring the class
-#   include example
-#
-# @param first The first parameter for this class
-# @param second The second parameter for this class
-class example_class(
-  String $first  = $example::params::first_arg,
-  Integer $second = $example::params::second_arg,
-) inherits example::params {
-  # ...
-}
-```
-
-The Strings elements appearing in the above comment block are:
-
-* Three comment lines, not prefixed with tags, give the class description.
-* The `@summary` YARD tag, which can be used for a short description of the class (fewer than 140 characters recommended).
-* 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. You may optionally include a parameter type in the `@param` tag. Strings will emit a warning and ignore the documented type should it differ from the actual type.
-
-With Puppet 3 code, you must always include the parameter type with the `@param` tag:
-
-```
-# @param first [String] The first parameter for this class.
-# @param second [Integer] The second parameter for this class.
-```
-
-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.
-define example_type(
-   Array[Integer] $ports = []
-) {
-  # ...
-}
-```
-
-### Documenting resource types and providers
-
-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
-  desc <<-DESC
-An example resource type.
-@example Using the type.
-  example { foo:
-    param => 'hi'
-  }
-DESC
-
-  newparam(:param) do
-    desc 'An example parameter.'
-    # ...
-  end
-
-  newproperty(:prop) do
-    desc 'An example property.'
-    #...
-  end
-
-  # ...  
-end
-```
- 
-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.
-# @!puppet.type.property [foo, bar, baz] my_prop Documentation for a dynamic property.
-Puppet::Type.newtype(:example) do
-  #...
-end
-```
-
-Document providers similarly, again using the `desc` method:
-
-```ruby
-Puppet::Type.type(:example).provide :platform do
-  desc 'An example provider.'
-
-  # ...
-end
-```
-
-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.
-
-Document types that use the new [Resource API](https://github.com/puppetlabs/puppet-resource_api):
-
-```ruby
-Puppet::ResourceApi.register_type(
-  name: 'database',
-  docs: 'An example database server resource type.',
-  attributes: {
-    ensure: {
-      type: 'Enum[present, absent, up, down]',
-      desc: 'What state the database should be in.',
-      default: 'up',
-    },
-    address: {
-      type: 'String',
-      desc: 'The database server name.',
-      behaviour: :namevar,
-    },
-    encrypt: {
-      type: 'Boolean',
-      desc: 'Whether or not to encrypt the database.',
-      default: false,
-      behaviour: :parameter,
-    },
-  },
-)
-```
-
-Here, the `docs` key acts like the `desc` method of the traditional resource type. Everything else is the same, except that now everything is a value in the data structure, not passed to methods.
-
-**Note**: Puppet Strings can not evaluate your Ruby code, so only certain static expressions are supported.
-
-### Documenting functions
-
-Puppet Strings supports the documenting of defined functions with the Puppet 4 API, the Puppet 3 API, or in the Puppet language itself.
-
-#### Document Puppet 4 functions
-
-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.
-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
-```
-
-**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 function contains multiple `dispatch` calls, Puppet Strings automatically creates `overload` tags to describe the function's overloads:
-
-```ruby
-# An example 4.x function.
-Puppet::Functions.create_function(:example) do
-  # Overload by string.
-  # @param first The first parameter.
-  # @return [String] Returns a string.
-  # @example Calling the function
-  #   example('hi')
-  dispatch :example_string do
-    param 'String', :first
-  end
-
-  # Overload by integer.
-  # @param first The first parameter.
-  # @return [Integer] Returns an integer.
-  # @example Calling the function
-  #   example(10)
-  dispatch :example_integer do
-    param 'Integer', :first
-  end
-
-  # ...
-```
-
-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 param1 [String] The first parameter.
-@param param2 [Integer] 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.
-
-#### Document Puppet language functions
-
-To document Puppet functions written in the Puppet language, use a YARD docstring before the function definition:
-
-```puppet
-# An example function written in Pupppet.
-# @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"
-}
-```
-
-**Note**: Puppet Strings automatically uses the parameter type information from the function's parameter list to document the parameter types.
-
-### Including examples in documentation
-
-The `@example` YARD tag adds usage examples to any Ruby or Puppet language code.
-
-```puppet
-# @example String describing what this example demonstrates.
-#   $content = example('world')
-#   if $content == 'world' {
-#     include world
-#   }
-function example(string $name) {
-  "hello $name"
-}
-```
-
-The string following the `@example` tag is an optional title which is displayed prominently above the code block.
-
-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.
-
-### Including multi-line tag descriptions
-
-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"
-}
-```
-
-## Reference
-
-### Available Strings tags
-
-* `@api`: Describes the resource as private or public, most commonly used with classes or defined types.
-* `@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).
-* `@param`: Documents a parameter with a given name, type and optional description.
-* `@!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.
-* `@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".
-* `@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.
-* `@since`: Lists the version in which the object was first added.
-* `@summary`: A short description of the documented item.
-
-### 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
-
-Use the `strings:generate` task to generate documentation:
-
-```
-$ rake strings:generate
-```
-
-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 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']
-```
-
-#### 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.
+By default, Puppet Strings outputs documentation as HTML, or you can specify JSON or Markdown output instead.
 
-This task:
+Strings generates reference documentation based on the code and Strings code comments in all Puppet and Ruby source files under the `./manifests/`, `./functions/`, `./lib/`, `./types/`, and `./tasks/` directories.
 
-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**.
+Strings outputs HTML of the reference information and the module README to the module's `./doc/` directory. This output can be rendered in any browser.
 
-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.
+JSON and Markdown output include the reference documentation only. Strings sends JSON output to either STDOUT or to a file. Markdown output is written to a REFERENCE.md file in the module's main directory.
 
-**Please note this operation is destructive if not used properly.**
+See the [Puppet Strings documentation](https://puppet.com/docs/puppet/latest/puppet_strings.html) for complete instructions for generating documentation with Strings. For code comment style guidelines and examples, see the [Puppet Strings style guide](https://puppet.com/docs/puppet/5.5/puppet_strings_style.html).
 
 ### Additional Resources
 
@@ -544,7 +63,7 @@ Here are a few other good resources for getting started with documentation:
 
 We love contributions from the community!
 
-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.
+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
 
@@ -561,7 +80,6 @@ Please log tickets and issues in our [JIRA tracker][JIRA]. A [mailing list](http
 
 There is also an active #puppet channel on the Freenode IRC network.
 
-We use semantic version numbers for our releases and recommend that users upgrade to
-patch releases and minor releases as they become available.
+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.