Improvements to file analysis docs

Fixed reference to wrong field name.
Added documentation of a function arg.
Added a couple references to other parts of the documentation.
Explained how not specifying extraction filename results in automatic
filename generation.
Several other minor clarifications.

scripts/base/files/extract/main.bro

@@ -12,14 +12,17 @@ export {
 	const default_limit = 0 &redef;
 
 	redef record Files::Info += {
-		## Local filenames of extracted file.
+		## Local filename of extracted file.
 		extracted: string &optional &log;
 	};
 
 	redef record Files::AnalyzerArgs += {
 		## The local filename to which to write an extracted file.
 		## This field is used in the core by the extraction plugin
-		## to know where to write the file to.  It's also optional.
+		## to know where to write the file to.  If not specified, then
+		## a filename in the format "extract-<source>-<id>" is
+		## automatically assigned (using the *source* and *id*
+		## fields of :bro:see:`fa_file`).
 		extract_filename: string &optional;
 		## The maximum allowed file size in bytes of *extract_filename*.
 		## Once reached, a :bro:see:`file_extraction_limit` event is

scripts/base/frameworks/files/main.bro

@@ -14,10 +14,11 @@ export {
 		LOG
 	};
 
-	## A structure which represents a desired type of file analysis.
+	## A structure which parameterizes a type of file analysis.
 	type AnalyzerArgs: record {
 		## An event which will be generated for all new file contents,
-		## chunk-wise.  Used when *tag* is
+		## chunk-wise.  Used when *tag* (in the
+		## :bro:see:`Files::add_analyzer` function) is
 		## :bro:see:`Files::ANALYZER_DATA_EVENT`.
 		chunk_event: event(f: fa_file, data: string, off: count) &optional;
 
@@ -47,7 +48,7 @@ export {
 		## the data traveled to.
 		rx_hosts: set[addr] &log;
 
-		## Connection UIDS over which the file was transferred.
+		## Connection UIDs over which the file was transferred.
 		conn_uids: set[string] &log;
 
 		## An identification of the source of the file data.  E.g. it
@@ -64,9 +65,10 @@ export {
 		## A set of analysis types done during the file analysis.
 		analyzers: set[string] &log;
 
-		## A mime type provided by libmagic against the *bof_buffer*, or
+		## A mime type provided by libmagic against the *bof_buffer*
-		## in the cases where no buffering of the beginning of file occurs,
+		## field of :bro:see:`fa_file`, or in the cases where no
-		## an initial guess of the mime type based on the first data seen.
+		## buffering of the beginning of file occurs, an initial
+		## guess of the mime type based on the first data seen.
 		mime_type: string &log &optional;
 
 		## A filename for the file if one is available from the source
@@ -132,7 +134,7 @@ export {
 	## t: the amount of time the file can remain inactive before discarding.
 	##
 	## Returns: true if the timeout interval was set, or false if analysis
-	##          for the *id* isn't currently active.
+	##          for the file isn't currently active.
 	global set_timeout_interval: function(f: fa_file, t: interval): bool;
 
 	## Adds an analyzer to the analysis of a given file.
@@ -144,7 +146,7 @@ export {
 	## args: any parameters the analyzer takes.
 	##
 	## Returns: true if the analyzer will be added, or false if analysis
-	##          for the *id* isn't currently active or the *args*
+	##          for the file isn't currently active or the *args*
 	##          were invalid for the analyzer type.
 	global add_analyzer: function(f: fa_file, 
 	                              tag: Files::Tag, 
@@ -154,10 +156,12 @@ export {
 	##
 	## f: the file.
 	##
+	## tag: the analyzer type.
+	##
 	## args: the analyzer (type and args) to remove.
 	##
 	## Returns: true if the analyzer will be removed, or false if analysis
-	##          for the *id* isn't currently active.
+	##          for the file isn't currently active.
 	global remove_analyzer: function(f: fa_file,
 	                                 tag: Files::Tag,
 	                                 args: AnalyzerArgs &default=AnalyzerArgs()): bool;
@@ -167,12 +171,12 @@ export {
 	## f: the file.
 	##
 	## Returns: true if analysis for the given file will be ignored for the
-	##          rest of its contents, or false if analysis for the *id*
+	##          rest of its contents, or false if analysis for the file
 	##          isn't currently active.
 	global stop: function(f: fa_file): bool;
 
-	## Translates a file analyzer enum value to a string with the analyzer's
+	## Translates a file analyzer enum value to a string with the
-	## name.
+	## analyzer's name.
 	##
 	## tag: The analyzer tag.
 	##

src/file_analysis/analyzer/extract/events.bif

@@ -1,6 +1,6 @@
 ## This event is generated when a file extraction analyzer is about
-## to exceed the maximum permitted file size allowed by
+## to exceed the maximum permitted file size allowed by the
-## *extract_size_limit* field of :bro:see:`Files::AnalyzerArgs`.
+## *extract_limit* field of :bro:see:`Files::AnalyzerArgs`.
 ## The analyzer is automatically removed from file *f*.
 ##
 ## f: The file.
@@ -13,7 +13,7 @@
 ##
 ## offset: The offset at which a file chunk is about to be written.
 ##
-## len:: The length of the file chunk about to be written.
+## len: The length of the file chunk about to be written.
 ##
 ## .. bro:see:: Files::add_analyzer Files::ANALYZER_EXTRACT
 event file_extraction_limit%(f: fa_file, args: any, limit: count, offset: count, len: count%);