From 0fe474e23278a9c68b1e687cb8c008b3ceeea698 Mon Sep 17 00:00:00 2001 From: Robin Sommer Date: Mon, 7 Oct 2013 15:53:46 -0700 Subject: [PATCH] Polishing the reference section of the manual. Mostly resorting and renaming a few things. --- doc/index.rst | 2 -- doc/scripts/builtins.rst | 4 ++-- doc/scripts/index.rst | 9 +++++---- doc/scripts/scripts.rst | 6 +++--- src/BroDoc.cc | 12 ++++++++---- src/bro.bif | 5 ++++- src/input.bif | 2 +- src/probabilistic/bloom-filter.bif | 6 +----- src/probabilistic/cardinality-counter.bif | 7 +------ src/probabilistic/top-k.bif | 7 +------ 10 files changed, 26 insertions(+), 34 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index ac667fc089..b79f1b67a6 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -18,8 +18,6 @@ Bro Documentation scripts/index.rst components/index.rst -* `Notice Index `_ (TODO: Move to reference - section, but can't figure out how to include it into toctree) * :ref:`General Index ` * :ref:`search` diff --git a/doc/scripts/builtins.rst b/doc/scripts/builtins.rst index 3605523839..aa1a097683 100644 --- a/doc/scripts/builtins.rst +++ b/doc/scripts/builtins.rst @@ -1,5 +1,5 @@ -Built-in Types and Attributes -============================= +Types and Attributes +==================== Types ----- diff --git a/doc/scripts/index.rst b/doc/scripts/index.rst index 8897504bb0..5a19bd23f0 100644 --- a/doc/scripts/index.rst +++ b/doc/scripts/index.rst @@ -7,13 +7,14 @@ Script Reference .. toctree:: :maxdepth: 1 - builtins - Built-In Functions (BIFs) - scripts packages - internal proto-analyzers file-analyzers + notices + builtins + Built-in Functions (BIFs) + internal + scripts diff --git a/doc/scripts/scripts.rst b/doc/scripts/scripts.rst index d454063002..8aceacf329 100644 --- a/doc/scripts/scripts.rst +++ b/doc/scripts/scripts.rst @@ -1,8 +1,8 @@ .. This is a stub doc to which broxygen appends during the build process -======================== -Index of All Bro Scripts -======================== +=============== +All Bro Scripts +=============== .. toctree:: :maxdepth: 1 diff --git a/src/BroDoc.cc b/src/BroDoc.cc index dd0e8ff37c..93d8a34848 100644 --- a/src/BroDoc.cc +++ b/src/BroDoc.cc @@ -610,8 +610,10 @@ void CreateProtoAnalyzerDoc(const char* filename) { FILE* f = fopen(filename, "w"); - fprintf(f, "Protocol Analyzer Reference\n"); - fprintf(f, "===========================\n\n"); + fprintf(f, "Protocol Analyzers\n"); + fprintf(f, "==================\n\n\n"); + fprintf(f, ".. contents::\n"); + fprintf(f, " :depth: 1\n\n"); WriteAnalyzerTagDefn(f, analyzer_mgr->GetTagEnumType(), "Analyzer"); @@ -640,8 +642,10 @@ void CreateFileAnalyzerDoc(const char* filename) { FILE* f = fopen(filename, "w"); - fprintf(f, "File Analyzer Reference\n"); - fprintf(f, "=======================\n\n"); + fprintf(f, "File Analyzers\n"); + fprintf(f, "==============\n\n"); + fprintf(f, ".. contents::\n"); + fprintf(f, " :depth: 1\n\n"); WriteAnalyzerTagDefn(f, file_mgr->GetTagEnumType(), "Files"); diff --git a/src/bro.bif b/src/bro.bif index 93b0da2dcc..f699c1e162 100644 --- a/src/bro.bif +++ b/src/bro.bif @@ -1,7 +1,10 @@ ##! 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. +##! inter-process communication and controlling protocol analyzer behavior. +##! +##! You'll find most of Bro's built-in functions that aren't protocol-specific in +##! this file. %%{ // C segment #include diff --git a/src/input.bif b/src/input.bif index d6a880d9e9..f7c4d37a67 100644 --- a/src/input.bif +++ b/src/input.bif @@ -1,4 +1,4 @@ -# functions and types for the input framework +##! Internal functions and types used by the input framework. module Input; diff --git a/src/probabilistic/bloom-filter.bif b/src/probabilistic/bloom-filter.bif index a495a603ae..f76a10a900 100644 --- a/src/probabilistic/bloom-filter.bif +++ b/src/probabilistic/bloom-filter.bif @@ -1,8 +1,4 @@ -# =========================================================================== -# -# Bloom Filter Functions -# -# =========================================================================== +##! Functions to create and manipulate Bloom filters. %%{ diff --git a/src/probabilistic/cardinality-counter.bif b/src/probabilistic/cardinality-counter.bif index 3f3f9653e6..f1113d73fc 100644 --- a/src/probabilistic/cardinality-counter.bif +++ b/src/probabilistic/cardinality-counter.bif @@ -1,9 +1,4 @@ -# =========================================================================== -# -# HyperLogLog Functions -# -# =========================================================================== - +##! Functions to create and manipulate probabilistic cardinality counters. %%{ #include "probabilistic/CardinalityCounter.h" diff --git a/src/probabilistic/top-k.bif b/src/probabilistic/top-k.bif index 9ad36cadef..2725fe0422 100644 --- a/src/probabilistic/top-k.bif +++ b/src/probabilistic/top-k.bif @@ -1,9 +1,4 @@ -# =========================================================================== -# -# Top-K Functions -# -# =========================================================================== - +##! Functions to probabilistically determine top-k elements. %%{ #include "probabilistic/Topk.h"