zeekygen/example.zeek

ZeekygenExample

This is an example script that demonstrates Zeekygen-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 into 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 Zeek Sphinx domain that’s good for “see alsos”, e.g.

See also: ZeekygenExample::a_var, ZeekygenExample::ONE, SSH::Info

And a custom directive does the equivalent references:

See also: ZeekygenExample::a_var, ZeekygenExample::ONE, SSH::Info

Namespace

ZeekygenExample

Imports

base/frameworks/notice, base/protocols/http, policy/frameworks/software/vulnerable.zeek

Summary

Redefinable Options

ZeekygenExample::an_option: set &redef

Add documentation for “an_option” here.

ZeekygenExample::option_with_init: interval &redef

Default initialization will be generated automatically.

State Variables

ZeekygenExample::a_var: bool

Put some documentation for “a_var” here.

ZeekygenExample::summary_test: string

The first sentence for a particular identifier’s summary text ends here.

ZeekygenExample::var_without_explicit_type: string

Types are inferred, that information is self-documenting.

Types

ZeekygenExample::ComplexRecord: record &redef

General documentation for a type “ComplexRecord” goes here.

ZeekygenExample::Info: record

An example record to be used with a logging stream.

ZeekygenExample::SimpleEnum: enum

Documentation for the “SimpleEnum” type goes here.

ZeekygenExample::SimpleRecord: record

General documentation for a type “SimpleRecord” goes here.

Redefinitions

Log::ID: enum

Notice::Type: enum

ZeekygenExample::SimpleEnum: enum

Document the “SimpleEnum” redef here with any special info regarding the redef itself.

ZeekygenExample::SimpleRecord: record

Document the record extension redef itself here.

New Fields

ZeekygenExample::SimpleRecord

field_ext: string &optional

Document the extending field like this.

Events

ZeekygenExample::an_event: event

Summarize “an_event” here.

Functions

ZeekygenExample::a_function: function

Summarize purpose of “a_function” here.

Detailed Interface

Redefinable Options

ZeekygenExample::an_option
Type

set [addr, addr, string]

Attributes

&redef

Default

{}

Add documentation for “an_option” here. The type/attribute information is all generated automatically.

ZeekygenExample::option_with_init
Type

interval

Attributes

&redef

Default

10.0 msecs

Default initialization will be generated automatically. More docs can be added here.

State Variables

ZeekygenExample::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.

ZeekygenExample::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.

ZeekygenExample::var_without_explicit_type
Type

string

Default

"this works"

Types are inferred, that information is self-documenting.

Types

ZeekygenExample::ComplexRecord
Type

record

field1: count

Counts something.

field2: bool

Toggles something.

field3: ZeekygenExample::SimpleRecord

Zeekygen automatically tracks types and cross-references are automatically inserted into generated docs.

msg: string &default = "blah" &optional

Attributes are self-documenting.

Attributes

&redef

General documentation for a type “ComplexRecord” goes here.

ZeekygenExample::Info
Type

record

ts: time &log

uid: string &log

status: count &log &optional

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).

ZeekygenExample::SimpleEnum
Type

enum

ZeekygenExample::ONE

Documentation for particular enum values is added like this. And can also span multiple lines.

ZeekygenExample::TWO

Or this style is valid to document the preceding enum value.

ZeekygenExample::THREE
ZeekygenExample::FOUR

And some documentation for “FOUR”.

ZeekygenExample::FIVE

Also “FIVE”.

Documentation for the “SimpleEnum” type goes here. It can span multiple lines.

ZeekygenExample::SimpleRecord
Type

record

field1: count

Counts something.

field2: bool

Toggles something.

field_ext: string &optional

Document the extending field like this. Or here, like this.

General documentation for a type “SimpleRecord” goes here. The way fields can be documented is similar to what’s already seen for enums.

Events

ZeekygenExample::an_event
Type

event (name: string)

Summarize “an_event” here. Give more details about “an_event” here.

ZeekygenExample::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: ZeekygenExample::a_function.

Parameters

name – Describe the argument here.

Functions

ZeekygenExample::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.

Parameters

  • tag – Function arguments can be described like this.

  • msg – Another param.

Returns

Describe the return type here.