I'd really like to be able to assign a class to POD documentation. Here's an
example of why:
class Widget is Bauble
#= A widget is a kind of bauble that can do stuff
{
has $.things; #= a collection of other stuff
#==XXX{
This variable needs to be replaced for political reasons
}
}
When extracting the documentation for this class, it should appear as such:
class Widget
base class: Bauble
A widget is a kind of bauble that can do stuff
Attributes:
$.things (simple scalar) -- a collection of other stuff
But when extracted with a flag requesting class XXX documentation, it should
include the additional line:
This variable needs to be replaced for political reasons
This has many uses:
- Keeping customer-visible and internal documentation in the same file
- Allowing easy access to just the documentation bits that you might be
interested in
- Could be extended to allow for injecting documentation into other
modules that are being extended, but in a way that allows access to the
original documentation on its own
- This might expose the implementation of features used to control
debugging, warnings (e.g. the equivalent of "no strict", but with
documentation as to why) and lint-like facilities
- One of my usual gripes about doc systems is that they document elements
of a program or library and not its function. Given this feature it would be
easy to distinguish between the two and perhaps even require either or both
depending on what's being parsed (e.g. a program might require only
functional documentation where a library might require both functional and
element-level docs).
