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

doc/scripts/example.bro

@@ -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,8 +189,17 @@ 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
 # of generated documentation and any "##"-stylized comments would also
 # be rendered there
@@ -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")
+        ]);
+    }

testing/btest/Baseline/doc.autogen-reST-example/example.rst

@@ -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::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`