The output reST filename now reflects the subdir information (by flattening
'/' path separators into the '^' character). This is to prevent file name
conflicts when generated reST docs, but during the CMake 'doc' target to
build HTML docs, everything gets unflattened.
A function prototype can be declared separately from where it's defined;
the doc framework should now recognize them as the same and combine
reST documentation associated with either case if both are present.
A script's public API wasn't simply definable as identifiers
for which ID::IsGlobal() is true, e.g. an unexported identifier with
SCOPE_MODULE will still pass that test and (incorrectly) be considered
public API.
Also, generated reST now omits empty interface sections.
A bro script's public interface is taken to mean any identifier declared
in the global scope that optionally is exported from some namespace/module.
Or more simply: ID::IsGlobal()
This functionality is better done manually by the script writer
embedding reST into the script summary section (##! comments).
This allows flexibility in choosing between different methods
to convey the same information (e.g. ":Author: <author>" or
the ".. codeauthor:: <author>" directive that Sphinx
configurations can recognize).
It's allowed for a script to "@load example.bro", but Sphinx doesn't want
that file extension for the purposes of generating cross-referencing links
to other documentation.
This adds a new subclass of EnumType, CommentedEnumType, and removes
any previous changes to EnumType that were done to support the
autodoc framework.
Dummy CommentedEnumType and ID's are constructed in parallel with the
real EnumType ID's during parsing and passed on to the autodoc framework.
This allows the generated documentation to track enum redefs, with
a special case being the "Notice" enum type.
* New bro runtime options: -Z or --doc-scripts enables documentation mode
* New BroDoc, BroBifDoc, and BroDocObj interfaces to support script
documentation
* Modifications to the bro scanner (scan.l) to get it to keep track of
which script is being scanned/parsed and which document is being generated
* Modifications to scan.l and the bro parser (parse.y) to produce/consume
script comments denoted with "##"
* Documentation is currently generated for the following
** Script author
** Script summary
** @load's
** capture_filters
** modules (namespaces)
Most of the remaining framework/infrastructure work should be in extracting
the interesting BroObj objects as the parser sees them and better formatting
the reST documents.
