BroxygenExample
This is an example script that demonstrates Broxygen-style documentation. It generally will make most sense when viewing the script’s raw source code and comparing to the HTML-rendered version.
Comments in the from ##!
are meant to summarize the script’s
purpose. They are transferred directly in to the generated
reStructuredText
(reST) document associated with the script.
Tip
You can embed directives and roles within ##
-stylized comments.
There’s also a custom role to reference any identifier node in the Bro Sphinx domain that’s good for “see alsos”, e.g.
See also: BroxygenExample::a_var
,
BroxygenExample::ONE
, SSH::Info
And a custom directive does the equivalent references:
See also: BroxygenExample::a_var
, BroxygenExample::ONE
, SSH::Info
Namespace: | BroxygenExample |
---|---|
Imports: | base/frameworks/notice, base/protocols/http, policy/frameworks/software/vulnerable.bro |
Source File: | /scripts/broxygen/example.bro |
BroxygenExample::an_option : set &redef |
Add documentation for “an_option” here. |
BroxygenExample::option_with_init : interval &redef |
Default initialization will be generated automatically. |
BroxygenExample::a_var : bool |
Put some documentation for “a_var” here. |
BroxygenExample::summary_test : string |
The first sentence for a particular identifier’s summary text ends here. |
BroxygenExample::var_without_explicit_type : string |
Types are inferred, that information is self-documenting. |
BroxygenExample::ComplexRecord : record &redef |
General documentation for a type “ComplexRecord” goes here. |
BroxygenExample::Info : record |
An example record to be used with a logging stream. |
BroxygenExample::SimpleEnum : enum |
Documentation for the “SimpleEnum” type goes here. |
BroxygenExample::SimpleRecord : record |
General documentation for a type “SimpleRecord” goes here. |
BroxygenExample::SimpleEnum : enum |
Document the “SimpleEnum” redef here with any special info regarding the redef itself. |
BroxygenExample::SimpleRecord : record |
Document the record extension redef itself here. |
Log::ID : enum |
|
Notice::Type : enum |
BroxygenExample::an_event : event |
Summarize “an_event” here. |
BroxygenExample::a_function : function |
Summarize purpose of “a_function” here. |
BroxygenExample::a_var
Type: | bool |
---|
Put some documentation for “a_var” here. Any global/non-const that isn’t a function/event/hook is classified as a “state variable” in the generated docs.
BroxygenExample::summary_test
Type: | string |
---|
The first sentence for a particular identifier’s summary text ends here. And this second sentence doesn’t show in the short description provided by the table of all identifiers declared by this script.
BroxygenExample::var_without_explicit_type
Type: | string |
---|---|
Default: | "this works" |
Types are inferred, that information is self-documenting.
BroxygenExample::ComplexRecord
Type: | |
---|---|
Attributes: |
General documentation for a type “ComplexRecord” goes here.
BroxygenExample::Info
Type: |
---|
An example record to be used with a logging stream. Nothing special about it. If another script redefs this type to add fields, the generated documentation will show all original fields plus the extensions and the scripts which contributed to it (provided they are also @load’ed).
BroxygenExample::SimpleEnum
Type: |
|
---|
Documentation for the “SimpleEnum” type goes here. It can span multiple lines.
BroxygenExample::SimpleRecord
Type: |
---|
General documentation for a type “SimpleRecord” goes here. The way fields can be documented is similar to what’s already seen for enums.
BroxygenExample::an_event
Type: | event (name: string ) |
---|
Summarize “an_event” here. Give more details about “an_event” here.
BroxygenExample::a_function should not be confused as a parameter
in the generated docs, but it also doesn’t generate a cross-reference
link. Use the see role instead: BroxygenExample::a_function
.
Name: | Describe the argument here. |
---|
BroxygenExample::a_function
Type: | function (tag: string , msg: string ) : string |
---|
Summarize purpose of “a_function” here. Give more details about “a_function” here. Separating the documentation of the params/return values with empty comments is optional, but improves readability of script.
Tag: | Function arguments can be described like this. |
---|---|
Msg: | Another param. |
Returns: | Describe the return type here. |