Improve documentation of input framework

scripts/base/frameworks/input/main.bro

@@ -1,18 +1,25 @@
 ##! The input framework provides a way to read previously stored data either
-##! as an event stream or into a bro table.
+##! as an event stream or into a Bro table.
 
 module Input;
 
 export {
 	type Event: enum {
+		## New data has been imported.
 		EVENT_NEW = 0,
+		## Existing data has been changed.
 		EVENT_CHANGED = 1,
+		## Previously existing data has been removed.
 		EVENT_REMOVED = 2,
 	};
 
+	## Type that defines the input stream read mode.
 	type Mode: enum {
+		## Do not automatically reread the file after it has been read.
 		MANUAL = 0,
+		## Reread the entire file each time a change is found.
 		REREAD = 1,
+		## Read data from end of file each time new data is appended.
 		STREAM = 2
 	};
 
@@ -47,11 +54,11 @@ export {
 	## abort. Defaults to false (abort).
 	const accept_unsupported_types = F &redef;
 
-	## TableFilter description type used for the `table` method.
+	## A table input stream type used to send data to a Bro table.
 	type TableDescription: record {
 		# Common definitions for tables and events
 
-		## String that allows the reader to find the source.
+		## String that allows the reader to find the source of the data.
 		## For `READER_ASCII`, this is the filename.
 		source: string;
 
@@ -61,7 +68,8 @@ export {
 		## Read mode to use for this stream.
 		mode: Mode &default=default_mode;
 
-		## Descriptive name. Used to remove a stream at a later time.
+		## Name of the input stream.  This is used by some functions to
+		## manipulate the stream.
 		name: string;
 
 		# Special definitions for tables
@@ -76,29 +84,32 @@ export {
 		## If this is undefined, then *destination* must be a set.
 		val: any &optional;
 
-		## Defines if the value of the table is a record (default), or a single value.
+		## Defines if the value of the table is a record (default), or a single
-		## When this is set to false, then *val* can only contain one element.
+		## value. When this is set to false, then *val* can only contain one
+		## element.
 		want_record: bool &default=T;
 
-		## The event that is raised each time a value is added to, changed in or
+		## The event that is raised each time a value is added to, changed in,
-		## removed from the table. The event will receive an Input::Event enum
+		## or removed from the table. The event will receive an
-		## as the first argument, the *idx* record as the second argument and
+		## Input::TableDescription as the first argument, an Input::Event
-		## the value (record) as the third argument.
+		## enum as the second argument, the *idx* record as the third argument
-		ev: any &optional; # event containing idx, val as values.
+		## and the value (record) as the fourth argument.
+		ev: any &optional;
 
 		## Predicate function that can decide if an insertion, update or removal
-		## should really be executed. Parameters are the same as for the event.
+		## should really be executed. Parameters have same meaning as for the
+		## event.
 		## If true is returned, the update is performed. If false is returned,
 		## it is skipped.
 		pred: function(typ: Input::Event, left: any, right: any): bool &optional;
 
-		## A key/value table that will be passed on the reader.
+		## A key/value table that will be passed to the reader.
-		## Interpretation of the values is left to the writer, but
+		## Interpretation of the values is left to the reader, but
 		## usually they will be used for configuration purposes.
 		config: table[string] of string &default=table();
 	};
 
-	## EventFilter description type used for the `event` method.
+	## An event input stream type used to send input data to a Bro event.
 	type EventDescription: record {
 		# Common definitions for tables and events
 
@@ -117,20 +128,26 @@ export {
 
 		# Special definitions for events
 
-		## Record describing the fields to be retrieved from the source input.
+		## Record type describing the fields to be retrieved from the input
+		## source.
 		fields: any;
 
-		## If this is false, the event receives each value in fields as a separate argument.
+		## If this is false, the event receives each value in *fields* as a
-		## If this is set to true (default), the event receives all fields in a single record value.
+		## separate argument.
+		## If this is set to true (default), the event receives all fields in
+		## a single record value.
 		want_record: bool &default=T;
 
 		## The event that is raised each time a new line is received from the
-		## reader. The event will receive an Input::Event enum as the first
+		## reader. The event will receive an Input::EventDescription record
-		## element, and the fields as the following arguments.
+		## as the first argument, an Input::Event enum as the second
+		## argument, and the fields (as specified in *fields*) as the following
+		## arguments (this will either be a single record value containing
+		## all fields, or each field value as a separate argument).
 		ev: any;
 
-		## A key/value table that will be passed on the reader.
+		## A key/value table that will be passed to the reader.
-		## Interpretation of the values is left to the writer, but
+		## Interpretation of the values is left to the reader, but
 		## usually they will be used for configuration purposes.
 		config: table[string] of string &default=table();
 	};
@@ -157,28 +174,29 @@ export {
 		## field will be the same value as the *source* field.
 		name: string;
 
-		## A key/value table that will be passed on the reader.
+		## A key/value table that will be passed to the reader.
-		## Interpretation of the values is left to the writer, but
+		## Interpretation of the values is left to the reader, but
 		## usually they will be used for configuration purposes.
 		config: table[string] of string &default=table();
 	};
 
-	## Create a new table input from a given source.
+	## Create a new table input stream from a given source.
 	##
 	## description: `TableDescription` record describing the source.
 	##
 	## Returns: true on success.
 	global add_table: function(description: Input::TableDescription) : bool;
 
-	## Create a new event input from a given source.
+	## Create a new event input stream from a given source.
 	##
 	## description: `EventDescription` record describing the source.
 	##
 	## Returns: true on success.
 	global add_event: function(description: Input::EventDescription) : bool;
 
-	## Create a new file analysis input from a given source.  Data read from
+	## Create a new file analysis input stream from a given source.  Data read
-	## the source is automatically forwarded to the file analysis framework.
+	## from the source is automatically forwarded to the file analysis
+	## framework.
 	##
 	## description: A record describing the source.
 	##
@@ -201,6 +219,10 @@ export {
 
 	## Event that is called when the end of a data source has been reached,
 	## including after an update.
+	##
+	## name: Name of the input stream.
+	##
+	## source: String that identifies the data source (such as the filename).
 	global end_of_data: event(name: string, source: string);
 }