Add reporter bif/framework documentation.

scripts/base/frameworks/reporter/main.bro

@@ -1,21 +1,36 @@
 ##! This framework is intended to create an output and filtering path for 
 ##! internal messages/warnings/errors.  It should typically be loaded to 
-##! avoid Bro spewing internal messages to standard error.
+##! avoid Bro spewing internal messages to standard error and instead log
+##! them to a file in a standard way.  Note that this framework deals with
+##! the handling of internally-generated reporter messages, for the
+##! interface into actually creating reporter messages from the scripting
+##! layer, use the built-in functions in :doc:`/scripts/base/reporter.bif`.
 
 module Reporter;
 
 export {
+	## The reporter logging stream identifier.
 	redef enum Log::ID += { LOG };
-	
+
+	## An indicator of reporter message severity.
 	type Level: enum { 
+		## Informational, not needing specific attention.
 		INFO, 
+		## Warning of a potential problem.
 		WARNING, 
+		## A non-fatal error that should be addressed, but doesn't
+		## terminate program execution.
 		ERROR
 	};
-	
+
+	## The record type which contains the column fields of the reporter log.
 	type Info: record {
+		## The network time at which the reporter event was generated.
 		ts:       time   &log;
+		## The severity of the reporter message.
 		level:    Level  &log;
+		## An info/warning/error message that could have either been
+		## generated from the internal Bro core or at the scripting-layer.
 		message:  string &log;
 		## This is the location in a Bro script where the message originated.
 		## Not all reporter messages will have locations in them though.

src/event.bif

@@ -5575,7 +5575,7 @@ event reporter_info%(t: time, msg: string, location: string%) &error_handler;
 ## location: A (potentially empty) string describing a location associated with the
 ##     warning.  
 ## 
-## .. bro:see:: reporter_warning reporter_error Reporter::info Reporter::warning
+## .. bro:see:: reporter_info reporter_error Reporter::info Reporter::warning
 ##    Reporter::error
 ## 
 ## .. note:: Bro will not call reporter events recursively. If the handler of any
@@ -5594,7 +5594,7 @@ event reporter_warning%(t: time, msg: string, location: string%) &error_handler;
 ## location: A (potentially empty) string describing a location associated with the
 ##     error.  
 ## 
-## .. bro:see:: reporter_error reporter_error Reporter::info Reporter::error
+## .. bro:see:: reporter_info reporter_warning Reporter::info Reporter::warning
 ##    Reporter::error
 ## 
 ## .. note:: Bro will not call reporter events recursively. If the handler of any

src/reporter.bif

@@ -1,3 +1,11 @@
+##! The reporter built-in functions allow for the scripting layer to
+##! generate messages of varying severity.  If no event handlers
+##! exist for reporter messages, the messages are output to stderr.
+##! If event handlers do exist, it's assumed they take care of determining
+##! how/where to output the messages.
+##!
+##! See :doc:`/scripts/base/frameworks/reporter/main` for a convenient
+##! reporter message logging framework.
 
 module Reporter;
 
@@ -5,6 +13,13 @@ module Reporter;
 #include "NetVar.h"
 %%}
 
+## Generates an informational message.
+##
+## msg: The informational message to report.
+##
+## Returns: Always true.
+##
+## .. bro:see:: reporter_info
 function Reporter::info%(msg: string%): bool
 	%{
 	reporter->PushLocation(frame->GetCall()->GetLocationInfo());
@@ -13,6 +28,13 @@ function Reporter::info%(msg: string%): bool
 	return new Val(1, TYPE_BOOL);
 	%}
 
+## Generates a message that warns of a potential problem.
+##
+## msg: The warning message to report.
+##
+## Returns: Always true.
+##
+## .. bro:see:: reporter_warning
 function Reporter::warning%(msg: string%): bool
 	%{
 	reporter->PushLocation(frame->GetCall()->GetLocationInfo());
@@ -21,6 +43,14 @@ function Reporter::warning%(msg: string%): bool
 	return new Val(1, TYPE_BOOL);
 	%}
 
+## Generates a non-fatal error indicative of a definite problem that should
+## be addressed. Program execution does not terminate.
+##
+## msg: The error message to report.
+##
+## Returns: Always true.
+##
+## .. bro:see:: reporter_error
 function Reporter::error%(msg: string%): bool
 	%{
 	reporter->PushLocation(frame->GetCall()->GetLocationInfo());
@@ -29,6 +59,11 @@ function Reporter::error%(msg: string%): bool
 	return new Val(1, TYPE_BOOL);
 	%}
 
+## Generates a fatal error on stderr and terminates program execution.
+##
+## msg: The error message to report.
+##
+## Returns: Always true.
 function Reporter::fatal%(msg: string%): bool
 	%{
 	reporter->PushLocation(frame->GetCall()->GetLocationInfo());