From eafe3eaa3229a1fa009c8cb829aab1bdcdc05f8e Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Mon, 20 Oct 2014 11:09:40 -0700 Subject: [PATCH] (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