The previous iteration eagerly grabbed all parameters when any puppet function
was created. We did not retrieve type information and would grab parameters
from any helper functions!
* Parse the Ruby AST for dispatch blocks which specify type information. Parse
the commands and arguments in those blocks.
* If there are no dispatch blocks, parse the AST for a ruby function with the
same name as the puppet function being created.
Prior to this commit, the acceptance tests were using the
rspec-html-matchers gem which we had removed because it does not
work with rspec 3.
In order to make the acceptance tests compatible with this change,
use string matching to check the HTML output instead and remove
the dependency on that gem.
Traverse the ruby AST to get method arguments and attach them to the code
object.
* Fixes spurious warnings issued by yard.
* Obviates the need for ugly regex code in the templates to retrieve
parameters from the source code.
Print the name of the parameter, the file, and the line number to stderr if the
parameter name does not match the name specified in the docs.
In order for this to be useful we need to present the user with the file name
and line number of the relevant parameters. This information needs to be
extracted from the code object and passed to the extract_param_details method.
Prior to this commit, some of the unit tests for strings relied on
the rspec-html-matchers gem, which does not seem to get along with
rspec 3. This meant that we had to tie our tests to rspec 2 which
has become too inconvenient.
In order to remove the gem, use simple string matching instead.
Update the Gemfile so that it no longer requires the matchers and
no longer has rspec tied to 2.7.
The debugger gem does not support ruby 2.0.
The byebug gem does not support ruby < 2.0.
Conditionally specify the right gem for the right version of ruby.
Prior to this commit, there were no tests to check if namespaces
were being properly generated (which was why we did not catch the
bug earlier). Add a test for defined type and host class handlers
to ensure that namespaces are properly generated in code objects.
Prior to this commit, puppet namespaces would be totally mangled when
processed by YARD since YARD is looking for Ruby namespaces where the
first letter of each segment must be uppercase.
In order to fix this, patch the relevant regular expression constants
in YARD so that they will accept segments that begin with uppercase
and lowercase letters.
An upstream pull request has been accepted into YARD to add another
regex constant which is necessary to complete this patch. However until
the next version of the YARD gem is released, we must include a temporary
hack to fix the problematic method in question (as it is not yet using
the added variable). Once the new version is released, the conditional
statement in code_ext/yard.rb can be removed entirely and all we will
need to do is patch the two regex constants.
Prior to this commit the Gemfile required rspec 2.14.0 which was
not available in the rubbygems mirror for Jenkins. To prevent the
spec tests from failing in Jenkins, use rspec 2.14.1 instead.
Prior to this commit, the fix for the 3x function issue was trying
to create an empty hash by calling Hash[ [[]] ] which in Ruby 1.9.3
produced and empty hash. However this is not the case in Ruby 2.0 and
up. Therefor, fix up the code so that it does not rely on Hash[ [[]] ]
creating and empty hash.
Prior to this commit, the Gemfile for strings did not specify which
version of rspec to use. When it started using rspec 3, the tests
that relied upon the rspec-html-matchers gem began to fail, likely
because that gem is not yet compatible with the new version of rspec.
Update the Gemfile so that we explicitly use an older version of
rspec to prevent tests from failing. We will have to either wait
for rspec-html-matchers to catch up or find a new way of testing
the HTML output before we can update to rspec 3.
Prior to this commit, the 3x function handler assumed that at
least two arguments (the name and one or more additional arguments)
were passed into newfunction when creating a 3x function. However
that is not actually required, the only argument needed is the name.
Update the 3x function handler so that it will not throw and exception
if only one argument is given.
Due to the changes in PUP-3900 which renamed Puppetx to PuppetX
and puppetx to puppet_x, strings was failing since the namespace
had not been updated in strings. In order to be compatible with this
change, update strings by renaming the namespace to match.
In order to ensure strings is still compatible with earlier versions
of puppet that don't include the namespace change, declare our own
PuppetX module. This way, if it is an older version and the namespace
is called Puppetx, the necessary PuppetX namespace will be created.
Prior to this commit, some of the comments in the code were not as
clear as they should have been and in some places comments were not
present where they were needed. Clean up existing comments and
add some for sections of code that are not very clear.
Additionally, some sections of the template for puppet namespaces
didn't really make sense to include, especially since we want the source
of truth for documentation of 3x functions to be the :doc string which is
passed in (not the comment block above the function). Thus, remove some of
the unneeded sections from the puppet namespace template.
Prior to this commit, the @param tag was not supported for 3x
functions since we could not derive any information about the
parameter from the code itself. Since we would still like users
to be able to document parameters if they wish, update the code so
that if a parameter is documented in the 3x :doc string it will be
displayed in the HTML.
Prior to this commit some of the logic used to extract data from
comments for templates was duplicated and a little messy. Create
the TemplateHelper class so that can be simplified and cleaned up
to make things more readable and efficient.
Prior to this commit there was a lot of duplicated code around
the generation of HTML for templates. Clean up and simplify code by
adding an HTMLHelper class with helper functions which can be used
in place of repeated logic.
Prior to this commit, all the HTML for puppet functions was just
generated by YARD as if it were a regular method. Since we ultimately
want to have our own custom templates, lay out the groundwork for customizing
the templates for functions and update the page headers to be more
readable.
At the moment the code is functional but contains a lot of duplication which
needs to be cleaned up.
Prior to this commit we were not calling htmlify on the docstring
for the description of a puppet class on defined type. This meant that
the raw string would be displayed without paying attention to any
potential markdown or rdoc formatting present.
Now the YARD method htmlify is being called on the docstring so that
it will be displayed properly.
Additionally clean up an unclear comment and fix a small bug in
the way parameter information is processed.
Prior to this commit there was a header and a sub-header for
defined types and classes. This was a little redundant so rather
than doing that, remove the sub-header and make the main header
more readable.
Do a bit of renaming and add some comments to make the processing
of parameter details a bit more clear. Additionally, update the
example in the README so that it will actually be parsed properly
by YARD (since YARD does not expect the one line title before the
description).
Prior to this commit if the type for a parameter was not specified
in the comment, nothing would be printed. Since we'll soon be adding
functionality which will determine the type programmatically, it
made more since to leave a place holder rather than nothing at all.
As such, the type is now listed as "TBD" if it is not specified
by the user in the comment.
Prior to this commit there were a few issues in the way information
about parameters was collected. The previous implementation relied
on parameters and their corresponding comments to be listed in the
same order. Now the parameter is matched to the corresponding comment
using the parameter name in the comment.
Additionally, if a comment is present for a parameter that does
not actually exist in the method it will appear as strike through
in the HTML.
Prior to this commit, most of the HTML created for documenting
puppet code was auto-generated by YARD, meaning that it was not
always presented in a way that was consistent or easy to read.
Now we are explicitly defining the HTML and styling that we want
to use when generating documentation for defined types and classes.
This means that we can define exactly how we want the output to look
so that is more compatible with puppet code.
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.
Ian Kronquist