You can pass a block to the constructor of the hostclass. For some reason Yard
is yielding the block twice. Our code is not yielding the block because we only
use yield in one place which is unrelated. I don't think this is intended
behavior on yard's part, it certainly seems odd, but we can dodge the question
and not have to wait for an upstream patch by extracting the logic from the
block and running it after the object has been initialized.
I forgot to include the code which extracts the type information for the code
object in the defined types handler. Without this we do not extract type
information from defined types so warnings cannot be emitted and types in the
documentation are listed as Unknown.
Subclasses have their superclass as part of their namespace and objects in the
subclass's namespace must be registered first.
Reverse the list of parsed objects so
that the classes will be handled and registered in the correct order.
Addresses @hlindberg's comment after PR #35 was closed.
Use the error message from the exception which is actually exactly what I
wanted to say anyway.
The transformer comment matching regex matched all whitespace after a comment.
Lines which were effectively "blank" and just had a comment would be erased.
Markdown lists need to end with a blank line. This messed up markdown
formatting.
The culprit is the regex /^\s*#\s/ which matches all of the comment ' #\n',
however we want to leave the newline alone for markdown to parse.
We replace the regex with /^\s*#[ \t]/ which will only match tabs or spaces
after the hash and leave our beloved newline alone.
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.
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, 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 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 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.
Prior to this commit, two require statements were in the wrong
order, causing strings to fail when running against anything that
required the future parser.
Now, those requires have been flipped and strings can run with
`--parser future` successfully.
Due to a merge conflict that was not properly resolved, a method
which did not exist was being called in the server action, causing
the action to fail. Remove the unneeded method call so that the
server action will work as intended.
The plugin.rb file really only did configuration of components that were already loaded.
By relocating to the strings.rb file, it provides a central place for all of the loading
and configuration of the strings components.
Prior to this commit, the requires for the puppetx portion of this
project were dealt with in each individual file. In order to make
the code more readable and the requires more clear, move them all
into the strings file.
Prior to this commit, many of the classes in this project were declared
in two lines. The first line would put them in the context of the module
they belonged to, and the second line would declare the class and deal with
inheritance. In order to make the code more readable and to allow
require statements to be moved to the top level, turn all class declarations
into one line statements.
Prior to this commit, the puppet strings project was using require_relative
to include other classes and modules. Due to some ambiguity and the fact
that the strings project shares some naming conventions with YARD, the
use of require_relative sometimes made it unclear what was being
included and where it was coming from. Now require is being used and although
this requires the full path, it makes it very clear where things are coming
from.
Refactor the actions module so that it is a class. This is important
because it allows us to keep `Puppet[]` calls out of the library and
have them in the face itself. Additionally, move a few things around
(like `check_required_features` since it makes require statements
cleaner) and clean up some comments.
Refactor the code in the strings face and extract much of the functionality
into a separate library in order to make the code more readable and
sustainable. Additionally, remove the `modules` action from the face
since it does not have a clear use case currently. However since the `server`
action depends on it, and it may be helpful to add other features in the future,
extract the functionality previously contained in `modules` into a helper
method.
Prior to this commit, the handlers and code objects which dealt with
puppet functions were referred to as `FutureParserFunctions` and
`ParseFunctions`. This naming convention will not make very much
sense going forward when the future parser becomes the primary
parser. Therefor, rename `FutureParserFunctions` to `Puppet4xFunctions`
and `ParserFunctions` to `Puppet3xFunctions`.
Since we don't want the name of the tool to reflect the fact that
it is using yard internally (this is an implementation detail), rename
the face to `strings`. Now when one wishes to generate documentation,
`puppet strings` will be used rather than `puppet yardoc`.
Ian Kronquist