Add summary documentation to bif files.

src/bro.bif

@@ -1,4 +1,8 @@
-# Definitions of Bro built-in functions.
+##! A collection of built-in functions that implement a variety of things
+##! such as general programming algorithms, string processing, math functions,
+##! introspection, type conversion, file/directory manipulation, packet
+##! filtering, inter-process communication and controlling protocol analyzer
+##! behavior.
 
 %%{ // C segment
 #include <math.h>

src/const.bif

@@ -1,4 +1,6 @@
-# Documentation and default values for these are located in policy/bro.init.
+##! Declaration of various scripting-layer constants that the Bro core uses
+##! internally.  Documentation and default values for the scripting-layer
+##! variables themselves are found in :doc:`/scripts/base/init-bare`.
 
 const ignore_keep_alive_rexmit: bool;
 const skip_http_data: bool;

src/event.bif

@@ -1,3 +1,8 @@
+##! The events that the C/C++ core of Bro can generate.  This is mostly
+##! consisting the high-level network events that protocol analyzers detect,
+##! but there are also several general-utilit yevents generated by internal
+##! Bro frameworks.
+
 #
 # Documentation conventions:
 #

src/strings.bif

@@ -1,4 +1,5 @@
-# Definitions of Bro built-in functions related to strings.
+##! Definitions of built-in functions related to string processing and
+##! manipulation.
 
 
 %%{ // C segment

src/types.bif

@@ -1,3 +1,4 @@
+##! Declaration of various types that the Bro core uses internally.
 
 enum dce_rpc_ptype %{
 	DCE_RPC_REQUEST,
@@ -134,8 +135,8 @@ enum createmode_t %{
 	EXCLUSIVE = 2,
 %}
 
-# Decleare record types that we want to access from the even engine. These are
-# defined in bro.init.
+# Decleare record types that we want to access from the event engine. These are
+# defined in init-bare.bro.
 type info_t: record;
 type fattr_t: record;
 type diropargs_t: record;