Minor improvements to logging framework documentation

scripts/base/frameworks/logging/main.bro

@@ -6,9 +6,10 @@
 module Log;
 
 export {
-	## Type that defines an ID unique to each log stream. Scripts creating new log
+	## Type that defines an ID unique to each log stream. Scripts creating new
-	## streams need to redef this enum to add their own specific log ID. The log ID
+	## log streams need to redef this enum to add their own specific log ID.
-	## implicitly determines the default name of the generated log file.
+	## The log ID implicitly determines the default name of the generated log
+	## file.
 	type Log::ID: enum {
 		## Dummy place-holder.
 		UNKNOWN
@@ -20,25 +21,24 @@ export {
 	## If true, remote logging is by default enabled for all filters.
 	const enable_remote_logging = T &redef;
 
-	## Default writer to use if a filter does not specify
+	## Default writer to use if a filter does not specify anything else.
-	## anything else.
 	const default_writer = WRITER_ASCII &redef;
 
-	## Default separator between fields for logwriters.
+	## Default separator to use between fields.
-	## Can be overwritten by individual writers.
+	## Individual writers can use a different value.
 	const separator = "\t" &redef;
 
-	## Separator between set elements.
+	## Default separator to use between elements of a set.
-	## Can be overwritten by individual writers.
+	## Individual writers can use a different value.
 	const set_separator = "," &redef;
 
-	## String to use for empty fields. This should be different from
+	## Default string to use for empty fields. This should be different
-	## *unset_field* to make the output unambiguous.
+	## from *unset_field* to make the output unambiguous.
-	## Can be overwritten by individual writers.
+	## Individual writers can use a different value.
 	const empty_field = "(empty)" &redef;
 
-	## String to use for an unset &optional field.
+	## Default string to use for an unset &optional field.
-	## Can be overwritten by individual writers.
+	## Individual writers can use a different value.
 	const unset_field = "-" &redef;
 
 	## Type defining the content of a logging stream.
@@ -63,7 +63,7 @@ export {
 	##       If no ``path`` is defined for the filter, then the first call
 	##       to the function will contain an empty string.
 	##
-	## rec: An instance of the streams's ``columns`` type with its
+	## rec: An instance of the stream's ``columns`` type with its
 	##      fields set to the values to be logged.
 	##
 	## Returns: The path to be used for the filter.
@@ -81,7 +81,8 @@ export {
 		terminating: bool;	##< True if rotation occured due to Bro shutting down.
 	};
 
-	## Default rotation interval. Zero disables rotation.
+	## Default rotation interval to use for filters that do not specify
+	## an interval. Zero disables rotation.
 	##
 	## Note that this is overridden by the BroControl LogRotationInterval
 	## option.
@@ -116,8 +117,8 @@ export {
 		## Indicates whether a log entry should be recorded.
 		## If not given, all entries are recorded.
 		##
-		## rec: An instance of the streams's ``columns`` type with its
+		## rec: An instance of the stream's ``columns`` type with its
-		##      fields set to the values to logged.
+		##      fields set to the values to be logged.
 		##
 		## Returns: True if the entry is to be recorded.
 		pred: function(rec: any): bool &optional;
@@ -125,10 +126,10 @@ export {
 		## Output path for recording entries matching this
 		## filter.
 		##
-		## The specific interpretation of the string is up to
+		## The specific interpretation of the string is up to the
-		## the used writer, and may for example be the destination
+		## logging writer, and may for example be the destination
 		## file name. Generally, filenames are expected to be given
-		## without any extensions; writers will add appropiate
+		## without any extensions; writers will add appropriate
 		## extensions automatically.
 		##
 		## If this path is found to conflict with another filter's
@@ -153,7 +154,7 @@ export {
 		##       then the first call to the function will contain an
 		##       empty string.
 		##
-		## rec: An instance of the streams's ``columns`` type with its
+		## rec: An instance of the stream's ``columns`` type with its
 		##      fields set to the values to be logged.
 		##
 		## Returns: The path to be used for the filter, which will be
@@ -177,7 +178,7 @@ export {
 		## If true, entries are passed on to remote peers.
 		log_remote: bool &default=enable_remote_logging;
 
-		## Rotation interval.
+		## Rotation interval. Zero disables rotation.
 		interv: interval &default=default_rotation_interval;
 
 		## Callback function to trigger for rotated files. If not set, the
@@ -207,9 +208,9 @@ export {
 
 	## Removes a logging stream completely, stopping all the threads.
 	##
-	## id: The ID enum to be associated with the new logging stream.
+	## id: The ID associated with the logging stream.
 	##
-	## Returns: True if a new stream was successfully removed.
+	## Returns: True if the stream was successfully removed.
 	##
 	## .. bro:see:: Log::create_stream
 	global remove_stream: function(id: ID) : bool;

scripts/base/frameworks/logging/writers/ascii.bro

@@ -1,15 +1,15 @@
 ##! Interface for the ASCII log writer.  Redefinable options are available
 ##! to tweak the output format of ASCII logs.
 ##!
-##! The ASCII writer supports currently one writer-specific filter option via
+##! The ASCII writer currently supports one writer-specific per-filter config
-##! ``config``: setting ``tsv`` to the string ``T`` turns the output into
+##! option: setting ``tsv`` to the string ``T`` turns the output into
 ##! "tab-separated-value" mode where only a single header row with the column
 ##! names is printed out as meta information, with no "# fields" prepended; no
-##! other meta data gets included in that mode.
+##! other meta data gets included in that mode.  Example filter using this::
 ##!
-##! Example filter using this::
+##!    local f: Log::Filter = [$name = "my-filter",
-##!
+##!                            $writer = Log::WRITER_ASCII,
-##!    local my_filter: Log::Filter = [$name = "my-filter", $writer = Log::WRITER_ASCII, $config = table(["tsv"] = "T")];
+##!                            $config = table(["tsv"] = "T")];
 ##!
 
 module LogAscii;
@@ -29,6 +29,8 @@ export {
 	## Format of timestamps when writing out JSON. By default, the JSON
 	## formatter will use double values for timestamps which represent the
 	## number of seconds from the UNIX epoch.
+	##
+	## This option is also available as a per-filter ``$config`` option.
 	const json_timestamps: JSON::TimestampFormat = JSON::TS_EPOCH &redef;
 
 	## If true, include lines with log meta information such as column names