More tweaks to generated script docs.

- The "private interface" section is still tracked, but no longer rendered.
  We can judge the usefulness of it later and add back if there's demand.

- Documentation of event handlers was being treated the same as event
  declarations.  Now handlers are tracked separately, but not currently
  rendered in the generated doc output since usefulness is questionable.

doc/scripts/example.bro

@@ -5,20 +5,6 @@
 ##! (reST) document's summary section.
 ##!
 ##! .. 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
 # a script's auto-generated documentation, but ones that use a

src/BroDoc.cc

@@ -227,6 +227,7 @@ void BroDoc::WriteDocFile() const
 		WriteToDoc("%s\n", packet_filter.c_str());
 		}
 
+/*
 	BroDocObjList::const_iterator it;
 	bool hasPrivateIdentifiers = false;
 
@@ -241,6 +242,7 @@ void BroDoc::WriteDocFile() const
 
 	if ( hasPrivateIdentifiers )
 		WriteInterface("Private Interface", '-', '~', false, false);
+*/
 	}
 
 void BroDoc::WriteInterface(const char* heading, char underline,

src/BroDoc.h

@@ -167,6 +167,18 @@ public:
 		all.push_back(o);
 		}
 
+	/**
+	 * Schedules documentation of an event handler declared by the script.
+	 * @param o A pointer to a BroDocObj which contains the internal
+	 *        Bro language representation of the script event handler and
+	 *        also any associated comments about it.
+	 */
+	void AddEventHandler(const BroDocObj* o)
+		{
+		event_handlers.push_back(o);
+		all.push_back(o);
+		}
+
 	/**
 	 * Schedules documentation of a function declared by the script.
 	 * @param o A pointer to a BroDocObj which contains the internal
@@ -228,6 +240,7 @@ protected:
 	BroDocObjList types;
 	BroDocObjList notices;
 	BroDocObjList events;
+	BroDocObjList event_handlers;
 	BroDocObjMap functions;
 	BroDocObjList redefs;
 

src/parse.y

@@ -1179,7 +1179,7 @@ func_hdr:
 				   FUNC_FLAVOR_EVENT, 0, $3);
 			$$ = $3;
 			if ( generate_documentation )
-				current_reST_doc->AddEvent(
+				current_reST_doc->AddEventHandler(
 					new BroDocObj($2, reST_doc_comments));
 			}
 	|	TOK_REDEF TOK_EVENT event_id func_params

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

@@ -15,20 +15,6 @@ 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:`policy/frameworks/software/vulnerable </scripts/policy/frameworks/software/vulnerable>`
 
 Summary
@@ -72,8 +58,6 @@ Events
 
 :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
@@ -233,10 +217,6 @@ Events
    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
@@ -309,40 +289,3 @@ Filters added::
     [ssl] = tcp port 443,
     [nntps] = tcp port 562
 
-Private Interface
------------------
-State Variables
-~~~~~~~~~~~~~~~
-.. bro:id:: Example::example_ports
-
-   :Type: :bro:type:`set` [:bro:type:`port`]
-   :Attributes: :bro:attr:`&redef`
-   :Default:
-
-   ::
-
-      {
-         443/tcp,
-         562/tcp
-      }
-
-Types
-~~~~~
-.. bro:type:: Example::PrivateRecord
-
-   :Type: :bro:type:`record`
-
-      field1: :bro:type:`bool`
-
-      field2: :bro:type:`count`
-
-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`
-