Add more cluster and communication framework documentation.

scripts/base/frameworks/cluster/__load__.bro

@@ -9,10 +9,10 @@ redef peer_description = Cluster::node;
 # Add a cluster prefix.
 @prefixes += cluster
 
-## If this script isn't found anywhere, the cluster bombs out.
-## Loading the cluster framework requires that a script by this name exists
-## somewhere in the BROPATH.  The only thing in the file should be the
-## cluster definition in the :bro:id:`Cluster::nodes` variable.
+# If this script isn't found anywhere, the cluster bombs out.
+# Loading the cluster framework requires that a script by this name exists
+# somewhere in the BROPATH.  The only thing in the file should be the
+# cluster definition in the :bro:id:`Cluster::nodes` variable.
 @load cluster-layout
 
 @if ( Cluster::node in Cluster::nodes )

scripts/base/frameworks/cluster/main.bro

@@ -1,21 +1,45 @@
+##! A framework for establishing and controlling a cluster of Bro instances.
+##! In order to use the cluster framework, a script named
+##! ``cluster-layout.bro`` must exist somewhere in Bro's script search path
+##! which has a cluster definition of the :bro:id:`Cluster::nodes` variable.
+##! The ``CLUSTER_NODE`` environment variable or :bro:id:`Cluster::node`
+##! must also be sent and the cluster framework loaded as a package like
+##! ``@load base/frameworks/cluster``.
+
 @load base/frameworks/control
 
 module Cluster;
 
 export {
+	## The cluster logging stream identifier.
 	redef enum Log::ID += { LOG };
-	
+
+	## The record type which contains the column fields of the cluster log.
 	type Info: record {
+		## The time at which a cluster message was generated.
 		ts:       time;
+		## A message indicating information about the cluster's operation.
 		message:  string;
 	} &log;
-	
+
+	## Types of nodes that are allowed to participate in the cluster
+	## configuration.
 	type NodeType: enum {
+		## A dummy node type indicating the local node is not operating
+		## within a cluster.
 		NONE,
+		## A node type which is allowed to view/manipulate the configuration
+		## of other nodes in the cluster.
 		CONTROL,
+		## A node type responsible for log and policy management.
 		MANAGER,
+		## A node type for relaying worker node communication and synchronizing
+		## worker node state.
 		PROXY,
+		## The node type doing all the actual traffic analysis.
 		WORKER,
+		## A node acting as a traffic recorder using the
+		## `Time Machine <http://tracker.bro-ids.org/time-machine>`_ software.
 		TIME_MACHINE,
 	};
 	
@@ -49,30 +73,38 @@ export {
 	
 	## Record type to indicate a node in a cluster.
 	type Node: record {
+		## Identifies the  type of cluster node in this node's configuration.
 		node_type:    NodeType;
+		## The IP address of the cluster node.
 		ip:           addr;
+		## The port to which the this local node can connect when
+		## establishing communication.
 		p:            port;
-		
 		## Identifier for the interface a worker is sniffing.
 		interface:    string      &optional;
-		
-		## Manager node this node uses.  For workers and proxies.
+		## Name of the manager node this node uses.  For workers and proxies.
 		manager:      string      &optional;
-		## Proxy node this node uses.  For workers and managers.
+		## Name of the proxy node this node uses.  For workers and managers.
 		proxy:        string      &optional;
-		## Worker nodes that this node connects with.  For managers and proxies.
+		## Names of worker nodes that this node connects with.
+		## For managers and proxies.
 		workers:      set[string] &optional;
+		## Name of a time machine node with which this node connects.
 		time_machine: string      &optional;
 	};
 	
 	## This function can be called at any time to determine if the cluster
 	## framework is being enabled for this run.
+	##
+	## Returns: True if :bro:id:`Cluster::node` has been set.
 	global is_enabled: function(): bool;
 	
 	## This function can be called at any time to determine what type of
 	## cluster node the current Bro instance is going to be acting as.
 	## If :bro:id:`Cluster::is_enabled` returns false, then
 	## :bro:enum:`Cluster::NONE` is returned.
+	##
+	## Returns: The :bro:type:`Cluster::NodeType` the calling node acts as.
 	global local_node_type: function(): NodeType;
 	
 	## This gives the value for the number of workers currently connected to,

scripts/base/frameworks/cluster/nodes/proxy.bro

@@ -1,3 +1,7 @@
+##! Redefines the options common to all proxy nodes within a Bro cluster.
+##! In particular, proxies are not meant to produce logs locally and they
+##! do not forward events anywhere, they mainly synchronize state between
+##! worker nodes.
 
 @prefixes += cluster-proxy
 

scripts/base/frameworks/cluster/nodes/worker.bro

@@ -1,3 +1,7 @@
+##! Redefines some options common to all worker nodes within a Bro cluster.
+##! In particular, worker nodes do not produce logs locally, instead they
+##! send them off to a manager node for processing.
+
 @prefixes += cluster-worker
 
 ## Don't do any local logging.

scripts/base/frameworks/cluster/setup-connections.bro

@@ -1,3 +1,6 @@
+##! This script establishes communication among all nodes in a cluster
+##! as defined by :bro:id:`Cluster::nodes`.
+
 @load ./main
 @load base/frameworks/communication