From b8778026a66ddf470cd80746c47ab7be0145ca2c Mon Sep 17 00:00:00 2001
From: Jon Siwek <jsiwek@ncsa.illinois.edu>
Date: Mon, 9 Jan 2012 16:11:41 -0600
Subject: [PATCH] Add summary documentation to bif files.

---
 src/bro.bif     | 6 +++++-
 src/const.bif   | 4 +++-
 src/event.bif   | 5 +++++
 src/strings.bif | 3 ++-
 src/types.bif   | 5 +++--
 5 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/src/bro.bif b/src/bro.bif
index c941d19c3b..c9a843e743 100644
--- a/src/bro.bif
+++ b/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>
diff --git a/src/const.bif b/src/const.bif
index 96630e300b..bc960caeb6 100644
--- a/src/const.bif
+++ b/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;
diff --git a/src/event.bif b/src/event.bif
index f3354ea2e2..a54010f2e4 100644
--- a/src/event.bif
+++ b/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:
 #
diff --git a/src/strings.bif b/src/strings.bif
index 5301dfcf5e..9c9bd576b1 100644
--- a/src/strings.bif
+++ b/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
diff --git a/src/types.bif b/src/types.bif
index da6bd6e031..4182c797e8 100644
--- a/src/types.bif
+++ b/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;