Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-10 10:38:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Adding example documentation for a script's use of logging features.

Browse source
This commit is contained in:
Jon Siwek 2011-05-06 19:23:15 -05:00
parent 2a21ebba2e
commit 80abad01a9
2 changed files with 102 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

45
doc/scripts/example.bro
View file

@ -6,6 +6,18 @@
##!
##! .. tip:: You can embed directives and roles within ``##``-stylized comments.
##!
##! A script's logging information has to be documented manually as minimally
##! shown below. Note that references may not always be possible (e.g.
##! anonymous filter functions) and a script may not need to document
##! each of "columns", "event", "filter" depending on exactly what it's doing.
##!
##! **Logging Stream ID:** :bro:enum:`Example::EXAMPLE`
##! :Columns: :bro:type:`Example::Info`
##! :Event: :bro:id:`Example::log_example`
##! :Filter: ``example-filter``
##! uses :bro:id:`Example::filter_func` to determine whether to
##! exclude the ``ts`` field
##!
##! :Author: Jon Siwek <jsiwek@ncsa.illinois.edu>
# Comments that use a single pound sign (#) are not significant to
@ -64,6 +76,12 @@ redef enum Notice += {
Notice_Four,
};
# Redef'ing the ID enumeration for logging streams is automatically tracked.
# Comments of the "##" form can be use to further document it, but it's
# better to do all documentation related to logging in the summary section
# as is shown above.
redef enum Log::ID += { EXAMPLE };
# Anything declared in the export section will show up in the rendered
# documentation's "public interface" section
@ -121,6 +139,13 @@ export {
msg: string &default="blah"; ##< attributes are self-documenting
} &redef;
## An example record to be used with a logging stream.
type Info: record {
ts: time &log;
uid: string &log;
status: count &log &optional;
};
############## options ################
# right now, I'm just defining an option as
# any const with &redef (something that can
@ -164,6 +189,15 @@ export {
## Give more details about "an_event" here.
## name: describe the argument here
global an_event: event(name: string);
## This is a declaration of an example event that can be used in
## logging streams and is raised once for each log entry.
global log_example: event(rec: Info);
}
function filter_func(rec: Info): bool
{
return T;
}
# this function is documented in the "private interface" section
@ -181,3 +215,14 @@ type PrivateRecord: record {
field1: bool;
field2: count;
};
event bro_init()
{
Log::create_stream(EXAMPLE, [$columns=Info, $ev=log_example]);
Log::add_filter(EXAMPLE, [
$name="example-filter",
$path="example-filter",
$pred=filter_func,
$exclude=set("ts")
]);
}

58
testing/btest/Baseline/doc.autogen-reST-example/example.rst
View file

@ -15,6 +15,18 @@ these comments are transferred directly into the auto-generated
.. tip:: You can embed directives and roles within ``##``-stylized comments.
A script's logging information has to be documented manually as minimally
shown below. Note that references may not always be possible (e.g.
anonymous filter functions) and a script may not need to document
each of "columns", "event", "filter" depending on exactly what it's doing.
**Logging Stream ID:** :bro:enum:`Example::EXAMPLE`
:Columns: :bro:type:`Example::Info`
:Event: :bro:id:`Example::log_example`
:Filter: ``example-filter``
uses :bro:id:`Example::filter_func` to determine whether to
exclude the ``ts`` field
:Author: Jon Siwek <jsiwek@ncsa.illinois.edu>
:Imports: :doc:`notice </policy/notice>`
@ -49,13 +61,20 @@ Types
goes here.
:bro:type:`Example::ComplexRecord`: :bro:type:`record` general documentation for a type "ComplexRecord" goes here
:bro:type:`Example::Info`: :bro:type:`record` An example record to be used with a logging stream.
====================================================== ==========================================================
Events
######
============================================== ==========================
================================================= =============================================================
:bro:id:`Example::an_event`: :bro:type:`event` Summarize "an_event" here.
============================================== ==========================
:bro:id:`Example::log_example`: :bro:type:`event` This is a declaration of an example event that can be used in
logging streams and is raised once for each log entry.
:bro:id:`bro_init`: :bro:type:`event`
================================================= =============================================================
Functions
#########
@ -66,6 +85,8 @@ Functions
Redefinitions
#############
===================================================== ========================================
:bro:type:`Log::ID`: :bro:type:`enum`
:bro:type:`Example::SimpleEnum`: :bro:type:`enum` document the "SimpleEnum" redef here
:bro:type:`Example::SimpleRecord`: :bro:type:`record` document the record extension redef here
@ -182,6 +203,18 @@ Types
general documentation for a type "ComplexRecord" goes here
.. bro:type:: Example::Info
:Type: :bro:type:`record`
ts: :bro:type:`time` :bro:attr:`&log`
uid: :bro:type:`string` :bro:attr:`&log`
status: :bro:type:`count` :bro:attr:`&log` :bro:attr:`&optional`
An example record to be used with a logging stream.
Events
~~~~~~
.. bro:id:: Example::an_event
@ -193,6 +226,17 @@ Events
:param name: describe the argument here
.. bro:id:: Example::log_example
:Type: :bro:type:`event` (rec: :bro:type:`Example::Info`)
This is a declaration of an example event that can be used in
logging streams and is raised once for each log entry.
.. bro:id:: bro_init
:Type: :bro:type:`event` ()
Functions
~~~~~~~~~
.. bro:id:: Example::a_function
@ -215,6 +259,12 @@ Functions
Redefinitions
~~~~~~~~~~~~~
:bro:type:`Log::ID`
:Type: :bro:type:`enum`
.. bro:enum:: Example::EXAMPLE Log::ID
:bro:type:`Example::SimpleEnum`
:Type: :bro:type:`enum`
@ -288,6 +338,10 @@ Types
Functions
~~~~~~~~~
.. bro:id:: Example::filter_func
:Type: :bro:type:`function` (rec: :bro:type:`Example::Info`) : :bro:type:`bool`
.. bro:id:: Example::function_without_proto
:Type: :bro:type:`function` (tag: :bro:type:`string`) : :bro:type:`string`