kienan
/
puppet-strings
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

(PDOC-63) Update README and JSON files. 

This commit updates the README and JSON documentation files to make them
consistent with the refactoring work.
This commit is contained in:
Peter Huene 2016-09-15 15:45:44 -07:00
parent 7897c70a52
commit 01913fcfb0
No known key found for this signature in database
GPG Key ID: 6B585C1742BE3C3C
3 changed files with 739 additions and 218 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

511
JSON.md Normal file
View File

@ -0,0 +1,511 @@
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.
Document Schema
===============
At the top level, there are five arrays in the JSON document:
| Document Key | Description |
| ---------------- | ----------------------------------------------------------------------------- |
| puppet_classes | The list of Puppet classes that were parsed. |
| 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 Classes
--------------
Each entry in the `puppet_classes` list is an object with the following attributes:
| Attribute Key | Description |
| ------------- | ----------------------------------------------------- |
| name | The name of the Puppet class. |
| file | The file defining the Puppet class. |
| line | The line where the Puppet class is defined. |
| inherits | The name of the Puppet class the class inherits from. |
| docstring | The *DocString* object for the class (see below). |
| defaults | The map of parameter names to default values. |
| source | The Puppet source code for the class. |
Defined Types
-------------
Each entry in the `defined_types` list is an object with the following attributes:
| Attribute Key | Description |
| ------------- | -------------------------------------------------------- |
| name | The name of the defined type. |
| file | The file defining the defined type. |
| line | The line where the defined type is defined. |
| docstring | The *DocString* object for the defined type (see below). |
| defaults | The map of parameter names to default values. |
| source | The Puppet source code for the defined type. |
Resource Types
--------------
Each entry in the `resource_types` list is an object with the following attributes:
| Attribute Key | Description |
| ------------- | --------------------------------------------------------- |
| name | The name of the resource type. |
| file | The file defining the resource type. |
| line | The line where the resource type is defined. |
| docstring | The *DocString* object for the resource type (see below). |
| properties | The list of properties for the resource type (see below). |
| parameters | The list of parameters for the resource type (see below). |
| features | The list of features for the resource type (see below). |
Each entry in the `properties` list is an object with the following attributes:
| Attribute Key | Description |
| ------------- | ------------------------------------------------------- |
| name | The name of the property. |
| description | The description of the property. |
| values | The array of acceptable string values for the property. |
| aliases | The map of new values aliased to existing values. |
| isnamevar | True if the property is a namevar or false if not. |
| default | The default value for the property. |
Each entry in the `parameters` list is an object with the following attributes:
| Attribute Key | Description |
| ------------- | -------------------------------------------------------- |
| name | The name of the parameter. |
| description | The description of the parameter. |
| values | The array of acceptable string values for the parameter. |
| aliases | The map of new values aliased to existing values. |
| isnamevar | True if the parameter is a namevar or false if not. |
| default | The default value for the parameter. |
Each entry in the `features` list is an object with the following attributes:
| Attribute Key | Description |
| ------------- | ------------------------------- |
| name | The name of the feature. |
| description | The description of the feature. |
Providers
---------
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. |
| 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. |
| commands | The string map of commands for the provider. |
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. |
DocString Objects
-----------------
For the above types, their docstrings are represented as an object with the following attributes:
| Attribute Key | Description DocString |
| ------------- | --------------------------------------------------- |
| text | The textual part of the DocString. |
| tags | The array of tag objects, if any are present. |
Each entry in the `tags` list is an object with the following properties:
| Attribute Key | Description |
| ------------- | ------------------------------------------------------- |
| tag_name | The name of the tag (e.g. param, return, etc.). |
| text | The descriptive text of the tag. |
| types | The array of types associated with the tag. |
| name | The name associated with the tag (e.g. parameter name). |
For Puppet 4.x functions with overloads, `overload` tags will contain three additional attributes:
| Attribute Key | Description |
| ------------- | ----------------------------------------------- |
| signature | The Puppet signature of the overload. |
| docstring | The *DocString* object describing the overload. |
| defaults | The map of parameter names to default values. |
Example JSON Document
---------------------
An example JSON document describing a Puppet class, defined type, resource type, provider, and Puppet functions:
```json
{
"puppet_classes": [
{
"name": "foo",
"file": "site.pp",
"line": 5,
"inherits": "foo::bar",
"docstring": {
"text": "A simple class.",
"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"
}
]
},
"defaults": {
"param3": "hi"
},
"source": "class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar {\n}"
}
],
"defined_types": [
{
"name": "dt",
"file": "site.pp",
"line": 12,
"docstring": {
"text": "A simple defined type.",
"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"
}
]
},
"defaults": {
"param3": "hi"
},
"source": "define dt(Integer $param1, $param2, String $param3 = hi) {\n}"
}
],
"resource_types": [
{
"name": "database",
"file": "database.rb",
"line": 43,
"docstring": {
"text": "An example database server resource type."
},
"properties": [
{
"name": "ensure",
"description": "What state the database should be in.",
"values": [
"present",
"absent",
"up",
"down"
],
"aliases": {
"up": "present",
"down": "absent"
},
"default": "up"
},
{
"name": "file",
"description": "The database file to use."
},
{
"name": "log_level",
"description": "The log level to use.",
"values": [
"debug",
"warn",
"error"
],
"default": "warn"
}
],
"parameters": [
{
"name": "address",
"description": "The database server name.",
"isnamevar": true
},
{
"name": "encryption_key",
"description": "The encryption key to use."
},
{
"name": "encrypt",
"description": "Whether or not to encrypt the database.",
"values": [
"true",
"false",
"yes",
"no"
],
"default": "false"
}
],
"features": [
{
"name": "encryption",
"description": "The provider supports encryption."
}
]
}
],
"providers": [
{
"name": "linux",
"type_name": "database",
"file": "linux.rb",
"line": 33,
"docstring": {
"text": "An example provider on Linux."
},
"confines": {
"kernel": "Linux",
"osfamily": "RedHat"
},
"features": [
"implements_some_feature",
"some_other_feature"
],
"defaults": {
"kernel": "Linux"
},
"commands": {
"foo": "/usr/bin/foo"
}
}
],
"puppet_functions": [
{
"name": "func",
"file": "site.pp",
"line": 20,
"type": "puppet",
"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"
]
}
]
},
"defaults": {
"param3": "hi"
},
"source": "function func(Integer $param1, $param2, String $param3 = hi) {\n}"
},
{
"name": "func3x",
"file": "func3x.rb",
"line": 1,
"type": "ruby3x",
"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"
]
}
]
},
"source": "Puppet::Parser::Functions.newfunction(:func3x, doc: <<-DOC\nAn example 3.x function.\n@param [String] first The first parameter.\n@param second The second parameter.\n@return [Undef] Returns nothing.\nDOC\n) do |*args|\nend"
},
{
"name": "func4x",
"file": "func4x.rb",
"line": 11,
"type": "ruby4x",
"docstring": {
"text": "An example 4.x function.",
"tags": [
{
"tag_name": "overload",
"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"
]
}
]
},
"name": "func4x"
},
{
"tag_name": "overload",
"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"
]
}
]
},
"name": "func4x"
}
]
},
"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"
}
]
}
```

311
README.md
View File

@ -2,12 +2,16 @@ 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 Face and plugin built on the [YARD Documentation Tool](http://yardoc.org/) and the Puppet 4 Parser. It is uses YARD and the Puppet Parser to generate HTML documentation about Puppet code and Puppet extensions written in Ruby. It will eventually replace the `puppet doc` command once feature parity has been achieved.
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] |
| *Issues* | [Puppet Labs' JIRA Tracker][JIRA] |
| *Issues* | [Puppet JIRA Tracker][JIRA] |
| *License* | [Apache 2.0][LICENSE] |
| *Change log* | [CHANGELOG.md][changelog] |
| *Contributing* | [CONTRIBUTING.md][contributing] and [COMMITTERS.md][committers] |
@ -19,19 +23,19 @@ A Puppet Face and plugin built on the [YARD Documentation Tool](http://yardoc.or
[contributing]: https://github.com/puppetlabs/puppet-strings/blob/master/CONTRIBUTING.md
[committers]: https://github.com/puppetlabs/puppet-strings/blob/master/COMMITTERS.md
Installation
Requirements
------------
In order to run strings you need to have the following software installed:
* Ruby 1.9.3 or newer
* Puppet 3.7 or newer
* The YARD RubyGem
* The `yard` Ruby gem
Installing the YARD Gem
-----------------------
**Installing the YARD Gem with Puppet**
The easiest way to install the YARD gem is with Puppet itself.
The easiest way to install the `yard` gem is with Puppet itself:
For Puppet 4.x:
```
@ -43,9 +47,12 @@ For Puppet 3.x:
$ puppet resource package yard provider=gem
```
Installing Strings Itself
Installing Puppet Strings
-------------------------
Strings can be installed using the [puppet-strings RubyGem](https://rubygems.org/gems/puppet-strings). To ensure it is installed in right place, it is best to install it using Puppet.
Strings can be installed using the [puppet-strings](https://rubygems.org/gems/puppet-strings) gem.
To ensure it is installed in right place, it is best to install it using Puppet:
For Puppet 4.x:
```
@ -68,12 +75,12 @@ $ puppet strings
```
This processes `README` and all Puppet and Ruby source files under the `./manifests/`, `./functions/`, and `./lib/`
directories by default.
directories by default and creates HTML documentation under the `./doc/` directory.
To document specific files:
```
$ puppet strings first.pp second.pp ...
$ puppet strings generate first.pp second.pp ...
```
To document specific directories:
@ -82,21 +89,19 @@ To document specific directories:
$ puppet strings 'modules/foo/lib/**/*.rb' 'modules/foo/manifests/**/*.pp' 'modules/foo/functions/**/*.pp' ...
```
Strings can also emit the generated documentation as JSON:
Strings can emit JSON documenting the Puppet extensions:
```
$ puppet strings generate manifest.pp --emit-json documentation.json
$ puppet strings generate --emit-json documentation.json
```
It can also print the JSON to stdout:
```
$ puppet strings generate manifest.pp --emit-json-stdout
$ puppet strings generate --emit-json-stdout
```
The schema for the JSON which Strings emits is [documented here](https://github.com/puppetlabs/puppet-strings/blob/master/json_dom.md).
Processing is delegated to the `yard` tool so some options listed in `yard help doc` are available. However, Puppet Faces do not support passing arbitrary options through a face so these options must be specified in a `.yardopts` file.
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:
@ -104,87 +109,210 @@ In addition to generating a directory full of HTML, you can also serve up docume
$ puppet strings server
```
Writing Compatible Documentation
--------------------------------
YARD Options
------------
Since the strings module is built around YARD, a few different comment formats can be used. YARD can work with RDoc, meaning it is backwards compatible with previously documented modules. Feel free to try out strings with RDoc, but we are planning to move to Markdown as the standard. You can configure which you would like YARD to use by adding a `.yardopts` file to the root of your module directory which specifies the desired format:
YARD options (see `yard help doc`) are supported in a `.yardopts` file in the same directory where `puppet strings` is run.
```
--markup markdown
```
Puppet Strings automatically sets the `markup` option to `markdown`, allowing your documentation strings to be in Markdown format.
While we have yet to decide exactly how documentation should work in the future, here are some very basic examples to get you started using the strings module. These are very much subject to change as we continue to work out a style guide.
Documenting Puppet Extensions
-----------------------------
### Functions
Here's an example of how you might document a 4x function:
### Puppet Classes / Defined Types
```ruby
# When given two numbers, returns the one that is larger.
# You could have a several line description here if you wanted,
# but I don't have much to say about this function.
#
# @example using two integers
# $bigger_int = max(int_one, int_two)
#
# @return [Integer] the larger of the two parameters
#
# @param num_a [Integer] the first number to be compared
# @param num_b [Integer] the second number to be compared
Puppet::Functions.create_function(:max) do
def max(num_a, num_b)
num_a >= num_b ? num_a : num_b
end
end
```
### Classes / Defined Types
Here's an example of how you might document a class:
To document Puppet classes and defined types, use a YARD docstring before the class or defined type definition:
```puppet
# This class is meant to serve as an example of how one might
# want to document a manifest in a way that is compatible.
# with the strings module
# An example class.
#
# @example when declaring the example class
# This is an example of how to document a Puppet class
#
# @example Declaring the class
# include example
#
# @param first_arg The first parameter for this class
# @param second_arg The second paramter for this class
class example (
$first_arg = $example::params::first_arg,
$second_arg = $exampe::params::second_arg,
) { }
# @param first The first parameter for this class
# @param second The second paramter for this class
class example_class(
String $first = $example::params::first_arg,
Integer $second = $example::params::second_arg,
) inherits example::params {
# ...
}
# An example defined type.
#
# 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 = []
) {
# ...
}
```
### Types and Providers
Strings will automatically extract the `@doc` provider docstring and any `desc` parameter/property docstrings.
***Note: unlike Ruby, Puppet is a typed language; Puppet Strings will automatically use the parameter type information to
document the parameters. A warning will be emitted if you document parameter types.***
Sometimes however, Puppet types use metaprogramming to create parameters and methods automatically. In those cases Strings will not be able to document them automatically (Strings doesn't execute the code that would generate those parameters), so you will need to provide hints on how to document your code. To document a parameter which is automatically created you must use the special directive `@!puppet.type.param` or `@!puppet.type.property` which may take types, the parameter or property name, and a description.
### Resource Types
To document custom resource types and their parameters/properties, use the `desc` method or assign a value to the `doc` attribute:
```ruby
# @!puppet.type.param my_parameter This parameter needs to be explicitly
# documented as it is generated by mk_resource_methods
Puppet::Type.newtype(:minifile) do
Puppet::Type.newtype(:example) do
desc <<-DESC
An example resource type.
@example Using the type.
example { foo:
param => 'hi'
}
DESC
@doc = "Manages files, including their content, ownership, and permissions.
The provider can manage symbolic links."
# This function does some metaprogramming on the new type.
mk_resource_methods
newparam(:path) do
desc <<-'EOT'
The path to the file to manage. Must be fully qualified.
EOT
# ... do stuff here
end
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:
```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
```
### Providers
To document providers, use the `desc` method or assign a value to the `doc` attribute:
```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.
***Note: Puppet Strings does not evaluate your Ruby code, so only certain static expressions are supported.***
### 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 3.x API
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 API
To document a function in the Puppet 4.x API, use a YARD docstring before the `create_function` call and 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 will automatically use the parameter type information from the `dispatch` block to document
the parameters. 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:
```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 will document both `example(String $first)` and `example(Integer $first)`.
## Puppet Language
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 will automatically use the parameter type information from the function's parameters to document
the parameters.***
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)
@ -239,29 +367,32 @@ This task aims to keep the `gh-pages` branch up to date with the current code an
***Please note this operation will be destructive if not used properly.***
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.
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.
Running Specs
-----
-------------
If you're going to be doing any development with puppet strings, it's essential that you can run the spec tests. You should simply have to do the following:
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:
$ bundle install --path .bundle/gems
$ bundle exec rake spec
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. In addition there is an active #puppet channel on Freenode.
We use semantic version numbers for our releases, and recommend that users stay as up-to-date as possible by upgrading to patch releases and minor releases as they become available.
Bugfixes and ongoing development will occur in minor releases for the current major version. Security fixes will be backported to a previous major version on a best-effort basis, until the previous major version is no longer maintained.
Caveats
-------
- Documentation blocks must immediately precede the documented code with no whitespace. This is because the comment extractor possesses the elegance and intelligence of a bag of hammers.
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.
- This project is very much a work in progress and may very well have undiscovered bugs and pitfalls. If you discover any of these, [please file a ticket](https://tickets.puppetlabs.com/browse/PDOC).
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
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.

121
json_dom.md
View File

@ -1,121 +0,0 @@
The Strings JSON Interchange Schema
===================================
Strings has two flags used to emit json.
* `--emit-json $FILE` Saves json to a file.
* `--emit-json-stdout` Prints json on stdout.
Top Level Structure
-------------------
The json outputted by strings is a single object which has 4 keys representing
the different types of Puppet code and extension functions Strings reads. The
value for each key is a list of json objects representing each puppet class,
function, etc.
Here is an example of the top level structure:
```json
{
"defined_types": [...],
"puppet_classes": [...],
"puppet_functions": [...],
"puppet_types": [...],
"puppet_providers": [...]
}
```
Defined Types
-------------
Each defined type or puppet class object has the following properties and values:
* `name`: A string representing the name of the object.
* `file`: The file the object came from. A string.
* `line`: The line in the file the object came from. A number.
* `docstring`: A string. The docstring describing the object.
* `examples`: A list of strings representing the content of the examples in the
docstring.
* `signatures`: A list of function signatures which may be supported by the
object. Each function signature is a json object whose keys are the
parameter names, and whose values are the types those parameters may take.
This is extracted from the code itself.
* `parameters`: An object whose keys are the parameter names and whose values
are the parameter's types or null if it has no types. This is extracted from
the docstring.
Puppet Functions
----------------
Both puppet 4x and 3x functions are represented as json objects kept in the
`puppet_functions` list. Puppet 4x functions have every property that 3x
functions have, as well as a few extras.
Puppet 3x functions have:
* `name`: A string representing the name of the
* `file`: The file the object came from. A string.
* `line`: The line in the file the object came from. A number.
* `docstring`: A string. The docstring describing our object.
* `function_api_version`: the number 3.
* `documented_params`: A object whose keys are the parameters which were
* documented and whose values are the types they may take, or null.
* `examples`: A list of strings representing the content of the examples in the
docstring.
Puppet 4x functions have everything 3x functions do as well as:
* The `function_api_version` is the number 4, not 3 (surprise!).
* `signatures`: A list of function signatures which may be supported by the
object. Each function signature is a json object whose keys are the parameter
names, and whose values are the types those parameters may take. This is
extracted from the code itself.
Puppet Types
------------
Each puppet type object has the following properties and values:
* `name`: A string representing the name of the object
* `file`: The file the object came from. A string.
* `line`: The line in the file the object came from. A number.
* `docstring`: A string. The docstring describing our object.
* `examples`: A list of strings representing the content of the examples in the
docstring.
* `parameters`: A list of objects with the following shape:
* `allowed_vales`: a list of strings representing the allowed values.
* `default`: a string or null.
* `docstring`: The docstring.
* `name`: the parameter name.
* `properties`: A list of objects with a shape very similar to parameters but
also including:
* `namevar`: A boolean.
* `features`: A list of objects representing possible features. They have the
following shape:
* `docstring`: The description of the feature.
* `methods`: null or a list of the available methods as strings.
* `name`: The feature's name.
Puppet Providers
----------------
Each puppet provider object has the following properties and values:
* `name`: A string representing the name of the object
* `file`: The file the object came from. A string.
* `line`: The line in the file the object came from. A number.
* `docstring`: A string. The docstring describing the object.
* `examples`: A list of strings representing the content of the examples in the
docstring.
* `commands`: A list of the names of the commands available.
* `confines`: An object whose keys are the confine keys and whose values are
the confine values.
* `defaults`: Similar to above.
* `features`: A list of strings representing the features this provider
supports.
* `type_name`: The type this provider accompanies.