For a bro script that is documented like:
## ...
## bar: ...
## Returns: ...
global foo(bar: string): string;
the generated reST documentation will automatically substitute meaningful
markup (reST field lists) for the parameter and return type comments
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.
They now appear at the bottom of generated docs.
Also, a "more info" link is added which can point to an arbitrary location
in any reST document processed by Sphinx.
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.
The documentation framework now sees "##Text" and "## Text" as
equivalent documentation comments. This prevents unintentional
indentation in the generated reST as a result of the later style, but
still allows embedded reST markup that relies on indentation of more
than two spaces to work as expected.
Comments associated with record fields and enums values are able
to span multiple "##"-stylized comments, allowing for more robust
reST markup to be embedded.
The documentation framework now tracks record fields through
a new CommentedTypeDecl subclass of TypeDecl that the parser constructs
in parallel with the real TypeDecl.
And (to be consistent with current conventions for reST documentation)
update places in the auto-documentation-generation framework
where tabs were used in the generated reST.
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.
"##" style comments before identifiers and "##<" style after identifiers
in the body of an enum type declaration will now show up in the
auto-generated reST documentation.
The scanner can now be told to start/stop producing new token types that
assist in documenting record field types (and eventually enums also).
TOK_DOC:
Produced on "##" style comments; documents the field that follows.
TOK_POST_DOC:
Produced on "##<" style comments; documents the previous field.
Changed BroType to track a char* instead of an ID* that represents
the declared type's identifier. It was also necessary to serialize
this information or else it can be lost (e.g. FieldDecl's in RecordType
always seem to get serialized at some point).
DescribeReST() functions added to many classes to get the output
closer to being reST compatible; still needs tweaking for Sphinx
(reST->HTML) compatibility.
Adds two extra shell scripts, one to handle either the c-shell
or bourne-shell syntax for setting environment variables, that can
be sourced in order to set the BROPATH directly in the current
shell/environment in a way that's compatible with running bro
from the build/ directory.
* origin/fastpath:
Fixing compiler warnings
Revert "Updating submodule to current master"
Remvoing leftover local variables that caused compile error on Mac OS X.
Updating submodule to current master
