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.
The default YARD template lumps anything that inherits from `NamespaceObject`
into the "Classes" list in HTML output. This patch alters the list generation
logic so that Namespaces parsed from manifests are listed in a separate
"Puppet Manifests" list.
The Future Parser will return nil if a manifest file contains no statements
(I.E. it is empty or full of comments). Handle these cases and ensure the
`enumerate` method of the YARD parser always returns an Array.
The `YARD::Registry#resolve` method assumes all subclasses of `NamespaceObject`
respond to `inheritance_tree`.
Ref commit d6a4791 for a similar case with `HostClassObject`.
This reverts commit a051319b34.
Added a FIXME note to `defined_type_object.rb` that explains why this patch was
originally created, why it was reverted and what unresolved issues remain.
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.
When creating an object, YARD will split the object name using `::` and
recursively create proxy namespaces for each component. Unfortunately this
process is optimized for Ruby and somewhat mangles Puppet code as Puppet class
names are not capitalized.
For now, dispense with this behavior by implementing `HostClassObject.new`.
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.
The YARD plugin is currently architected using `require_relative` so that it
can be loaded outside of Puppet. Unfortunately, `require_relative` first
appeared in Ruby 1.9.1.
Achieve compatibility using the Backports gem.
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.
The `YARDStatement` class is an adaptor that composes a `Pops::Model` instance
along with applicable `Pops::Adapter` and presents a familiar interface for
`YARD::Handler` objects to work with.
Start building a YARD parser. Parsing and comment extraction has been moved out
of the yardoc face and into the new `Puppetx::Yardoc::YARD::PuppetParser`
class. The old `Commentor` class from the Util module has been renamed to
`Puppetx::Yardoc::Pops::YARDTransformer`.
`puppet yardoc` is still capable of extracting docstrings for node, class and
type definitions from a single manifest file.
Charlie Sharpsteen