From 408d875986ec581227ff96cf5b78d6004f90a75a Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Mon, 20 Oct 2014 10:17:52 -0700 Subject: [PATCH 1/2] (PDOC-13) Add documentation examples to README In order to make it easier for users, give some basic examples in the README of how write documentation that is compatible with strings. Also provide a few resources for getting started. --- README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 58 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 827654a..4ed3ea9 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,6 @@ the `puppet doc` command once feature parity has been achieved. Installation ------------ - In order to run strings you need to have the following software installed: * Ruby 1.9.3 or newer @@ -22,7 +21,6 @@ on the [Puppet Forge](https://forge.puppetlabs.com/puppetlabs/strings) and can b Running Puppet Strings ----- - If you cloned the repository into your `modulepath` and installed the needed gems, you can do the following to document a module: @@ -43,6 +41,64 @@ documentation for all your modules using the `server` action: $ puppet strings server +Writing Compatible Documentation +----- +Since the strings module is built around YARD, a few different comment formats are compatible. +YARD can work with RDoc, meaning it is backwards compatible with previously documented modules. +However, we would ultimately like to move away from RDoc use Markdown instead. 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: + + --markup markdown + +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. + +Here's an example of how you might document a 4x function: + + # 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) + # + # See further documentation somewhere else + # + # @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 + +And here's an example of how you might document a class: + + # Class: Example + # + # 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 + # + # @example { "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, + ) { } + +Here are a few other good resources for getting started with documentation: + + * [Module README Template](https://docs.puppetlabs.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) + License ----- See [LICENSE](https://github.com/puppetlabs/puppetlabs-strings/blob/master/LICENSE) file. From eafe3eaa3229a1fa009c8cb829aab1bdcdc05f8e Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Mon, 20 Oct 2014 11:09:40 -0700 Subject: [PATCH 2/2] (maint) Exclude files that cause YARD errors Running `puppet strings server` generates documentation for all modules in your modulepath, meaning that it also generates HTML for strings itself. Since there are parts of strings that are not meant to be documented with YARD, exclude the files that cause error messages so that `puppet strings server` is not needlessly noisy. Additionally, make a few suggested changes to the README to make it clearer and easier to read. --- .yardopts | 3 ++- README.md | 13 ++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.yardopts b/.yardopts index b9395b0..e30cb06 100644 --- a/.yardopts +++ b/.yardopts @@ -1 +1,2 @@ ---exclude lib/puppetx/yardoc/yard/templates +--exclude lib/puppetx/puppetlabs/strings/yard/templates/ +--exclude lib/puppetx/puppetlabs/strings/yard/code_objects/host_class_object.rb diff --git a/README.md b/README.md index 4ed3ea9..5cc9ffa 100644 --- a/README.md +++ b/README.md @@ -43,11 +43,11 @@ documentation for all your modules using the `server` action: Writing Compatible Documentation ----- -Since the strings module is built around YARD, a few different comment formats are compatible. +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. -However, we would ultimately like to move away from RDoc use Markdown instead. 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: +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: --markup markdown @@ -64,8 +64,6 @@ Here's an example of how you might document a 4x function: # @example using two integers # $bigger_int = max(int_one, int_two) # - # See further documentation somewhere else - # # @return [Integer] the larger of the two parameters # # @param num_a [Integer] the first number to be compared @@ -84,7 +82,8 @@ And here's an example of how you might document a class: # want to document a manifest in a way that is compatible. # with the strings module # - # @example { "example": } + # @example when declaring the example class + # include example # # @param first_arg The first parameter for this class # @param second_arg The second paramter for this class