This patch recurses into any `create_function` block and processes any
`dispactch` blocks contained within. The implementation assumes docstrings will
be provided as a comment block, but this is just a temporary placeholder.
Idealy, the contents of the `dispatch` block would be processed to produce an
`@override` tag for 4.x functions.
All Future Parser functions are documented using a standard YARD comment block.
This commit adds a new code object that watches for `create_function` and
generates a YARD `CodeObject::MethodObject` containing the docstring.
The Puppet Core uses a `.yardopts` file that hides all docstrings that do not
have an API tag. This patch is a hack that allows `puppet yardoc` to extract
documentation for parser functions shipped in the core.
FIXME: This isn't the right way to solve the problem. The right way to solve
the problem is to adjust the Puppet `.yardopts` file to a sane value.
This handler triggers on all occurrences of `newfunction` and parses the
parameters passed to that method in order to generate documentation. The
implementation is a good experiment in extracting documentation without
evaluating Ruby code. However, the generality of this approach may ultimately
be doomed by the use of metaprogramming in custom Types and Providers.
Puppet Yardoc now generates documentation for defined types in addition to host
classes. The actual change was fairly small, however this patch is quite large
as most of the host class bits were re-architected to inherit from defined
types. Host classes are basically the same as defined types with the addition
of inheritance. Pops also models Host Class using a similar inheritance
relationship.
Re-worked the YARD transformer and handlers to attach parameters to the
resulting code objects. Some architectural debt was incurred in the interests
of producing a working prototype quickly.
Instead of documenting Puppet classes using `ClassObject`, use a custom
subclass of `NamespaceObject`. This is done because Puppet classes are not Ruby
classes and will have components that don't fit into the model offered by
`ClassObject`.
This commit also adds a couple of monkey patches to integrate the new
`:hostclass` into YARD tooling and the beginnings of some custom templating.
Use `require_relative` for all components under Puppetx. This makes it possible
to load `pupetx/yardoc/yard/plugin` outside of Puppet as a YARD plugin.
Also fix the `yardoc` face so that Puppetx bits are loaded _after_ feature
checks.
Charlie Sharpsteen