Fixes to the progdoc.

17 files changed, 73 insertions, 74 deletions

diff --git a/conf/cf-lex.l b/conf/cf-lex.l
index 49984f55..9dfe10ea 100644
--- a/conf/cf-lex.l
+++ b/conf/cf-lex.l
@@ -10,12 +10,12 @@
  * DOC: Lexical analyzer
  *
  * The lexical analyzer used for configuration files and CLI commands
- * is generated using the |flex| tool accompanied with a couple of
+ * is generated using the |flex| tool accompanied by a couple of
  * functions maintaining the hash tables containing information about
  * symbols and keywords.
  *
  * Each symbol is represented by a &symbol structure containing name
- * of the symbol, its scope, symbol class (%SYM_PROTO for a name of a protocol,
+ * of the symbol, its lexical scope, symbol class (%SYM_PROTO for a name of a protocol,
  * %SYM_NUMBER for a numeric constant etc.) and class dependent data.
  * When an unknown symbol is encountered, it's automatically added to the
  * symbol table with class %SYM_VOID.
@@ -454,7 +454,7 @@ cf_symbol_class_name(struct symbol *sym)
  * the |gen_parser.m4| script.
  *
  * Grammar snippets are files (usually with extension |.Y|) contributed
- * by various BIRD modules to provide information about syntax of their
+ * by various BIRD modules in order to provide information about syntax of their
  * configuration and their CLI commands. Each snipped consists of several
  * section, each of them starting with a special keyword: |CF_HDR| for
  * a list of |#include| directives needed by the C code, |CF_DEFINES|
diff --git a/conf/conf.c b/conf/conf.c
index 232be3fd..d6e2425e 100644
--- a/conf/conf.c
+++ b/conf/conf.c
@@ -9,9 +9,9 @@
 /**
  * DOC: Configuration manager
  *
- * Configuration of BIRD is complex, but straightforward. There exist three
+ * Configuration of BIRD is complex, yet straightforward. There exist three
  * modules taking care of the configuration: config manager (which takes care
- * of storage of config information and controls switching between configs),
+ * of storage of the config information and controls switching between configs),
  * lexical analyzer and parser.
  *
  * The configuration manager stores each config as a &config structure
@@ -27,7 +27,7 @@
  *
  * Loading of new configuration is very simple: just call config_alloc()
  * to get a new &config structure, then use config_parse() to parse a
- * configuration file and fill all information in the structure
+ * configuration file and fill all fields of the structure
  * and finally ask the config manager to switch to the new
  * config by calling config_commit().
  *
diff --git a/doc/prog-intro.sgml b/doc/prog-intro.sgml
index ac45ab24..f584f69b 100644
--- a/doc/prog-intro.sgml
+++ b/doc/prog-intro.sgml
@@ -2,12 +2,12 @@
 
 <sect>Introduction
 
-<p>This document describes the internal workings of the BIRD, its architecture,
+<p>This document describes the internal workings of BIRD, its architecture,
 design decisions and rationale behind them. It also contains documentation on
 all the essential components of the system and their interfaces.
 
 <p>Routing daemons are very complicated things which need to act in real time
-to complex sequences external events, react correctly even to the most erroneous behavior
+to complex sequences of external events, respond correctly even to the most erroneous behavior
 of their environment and still handle enormous amount of data with reasonable
 speed. Due to all of this, their design is very tricky as one needs to carefully
 balance between efficiency, stability and (last, but not least) simplicity of
@@ -21,7 +21,7 @@ by the program source itself together with comments contained therein.
 
 <p>When planning the architecture of BIRD, we've taken a close look at the other existing routing
 daemons and also at some of the operating systems used on dedicated routers, gathered all important
-features and added lots of new ones to overcome their shortcomings and better match the requirements
+features and added lots of new ones to overcome their shortcomings and to better match the requirements
 of routing in today's Internet: IPv6, policy routing, route filtering and so on. From this
 planning, the following set of design goals has arisen:
 
@@ -36,8 +36,8 @@ This leads to abstraction of IP addresses and operations on them.
 <item><it>Minimize OS dependent code to make porting as easy as possible.</it>
 Unfortunately, such code cannot be avoided at all as the details of communication with
 the IP stack differ from OS to OS and they often vary even between different
-versions of the same OS, but we can isolate such code in special modules and
-do the porting by changing just these modules.
+versions of the same OS. But we can isolate such code in special modules and
+do the porting by changing or replacing just these modules.
 Also, don't rely on specific features of various operating systems, but be able
 to make use of them if they are available.
 
@@ -62,7 +62,7 @@ to read the new configuration and smoothly adapt to it without disturbing parts
 the routing process which are not affected by the change.
 
 <item><it>Be able to be controlled online.</it>
-In addition to online reconfiguration, a routing daemon should be able to communicate
+In addition to the online reconfiguration, a routing daemon should be able to communicate
 with the user and with many other programs (primarily scripts used for network maintenance)
 in order to make it possible to inspect contents of routing tables, status of all
 routing protocols and also to control their behavior (i.e., it should be possible
@@ -71,7 +71,7 @@ this, we implement a simple command-line protocol based on those used by FTP and
 (that is textual commands and textual replies accompanied by a numeric code which makes
 them both readable to a human and easy to recognize in software).
 
-<item><it>Respond to all protocol events in real time.</it>
+<item><it>Respond to all events in real time.</it>
 A typical solution to this problem is to use lots of threads to separate the workings
 of all the routing protocols and also of the user interface parts and to hope that
 the scheduler will assign time to them in a fair enough manner. This is surely a good
@@ -88,18 +88,18 @@ the following types of modules:
 
 <descrip>
 
-<tagp>Core modules</tagp> implement the core functions of BIRD as taking care
+<tagp>Core modules</tagp> implement the core functions of BIRD: taking care
 of routing tables, keeping protocol status, interacting with the user using
 the Command-Line Interface (to be called CLI in the rest of this document)
 etc.
 
 <tagp>Library modules</tagp> form a large set of various library functions
 implementing several data abstractions, utility functions and also functions
-which are a part of standard libraries on some systems, but missing on other
+which are a part of the standard libraries on some systems, but missing on other
 ones.
 
 <tagp>Resource management modules</tagp> take care of resources, their allocation
-and automatic freeing when the module having requested them ceases to exist.
+and automatic freeing when the module having requested shuts itself down.
 
 <tagp>Configuration modules</tagp> are fragments of lexical analyzer,
 grammar rules and the corresponding snippets of C code. For each group
@@ -120,7 +120,7 @@ interface to the CLI.
 
 <sect>Implementation
 
-<p>BIRD has been written in GNU C. We've considered using of C++, but we've
+<p>BIRD has been written in GNU C. We've considered using C++, but we've
 preferred the simplicity and straightforward nature of C which gives us fine
 control over all implementation details and on the other hand enough
 instruments to build the abstractions we need.
diff --git a/lib/event.c b/lib/event.c
index 788aab42..9b5870d3 100644
--- a/lib/event.c
+++ b/lib/event.c
@@ -13,12 +13,10 @@
  * Since BIRD is single-threaded, it requires long lasting tasks to be split to smaller
  * parts, so that no module can monopolize the CPU. To split such a task, just create
  * an &event resource, point it to the function you want to have called and call ev_schedule()
- * to ask the core to run the event when nothing more important will require attention.
+ * to ask the core to run the event when nothing more important requires attention.
  *
  * You can also define your own event lists (the &event_list structure), enqueue your
  * events in them and explicitly ask to run them.
- *
- * The actual implementation is system dependent.
  */
 
 #include "nest/bird.h"
diff --git a/lib/resource.sgml b/lib/resource.sgml
index df02bbfc..6b6dd7d2 100644
--- a/lib/resource.sgml
+++ b/lib/resource.sgml
@@ -21,7 +21,7 @@ modules of BIRD, deallocates everything automatically when a module
 shuts down and it's is able to print out the list of resources and
 the corresponding modules they are allocated by.
 
-<p>Each allocated resource (and from now we'll speak about allocated
+<p>Each allocated resource (from now we'll speak about allocated
 resources only) is represented by a structure starting with a standard
 header (struct <struct/resource/) consisting of a list node (resources are
 often linked to various lists) and a pointer to <struct/resclass/ -- a resource
diff --git a/lib/slab.c b/lib/slab.c
index 736dcb82..c6a56f7b 100644
--- a/lib/slab.c
+++ b/lib/slab.c
@@ -19,10 +19,10 @@
  * constructors and destructors.
  *
  * When the |DEBUGGING| switch is turned on, we automatically fill all
- * newly allocated and freed blocks with a special patterns to make detection
+ * newly allocated and freed blocks with a special pattern to make detection
  * of use of uninitialized or already freed memory easier.
  *
- * Example: Nodes of a FIB are allocated from a Slab.
+ * Example: Nodes of a FIB are allocated from a per-FIB Slab.
  */
 
 #include <stdlib.h>
diff --git a/nest/cli.c b/nest/cli.c
index 30ac7510..a917bcb3 100644
--- a/nest/cli.c
+++ b/nest/cli.c
@@ -26,12 +26,12 @@
  * a continuation line, the whole prefix can be replaced by a single
  * white space character.
  *
- * Reply codes starting with 0 describe `action successfully completed' messages,
+ * Reply codes starting with 0 stand for `action successfully completed' messages,
  * 1 means `table entry', 8 `runtime error' and 9 `syntax error'.
  *
  * Each CLI session is internally represented by a &cli structure and a
  * resource pool containing all resources associated with the connection,
- * so that it can be easily freed whenever the connection closes, not depending
+ * so that it can be easily freed whenever the connection gets closed, not depending
  * on the current state of command processing.
  *
  * The CLI commands are declared as a part of the configuration grammar
@@ -40,9 +40,9 @@
  * it's switched to a special mode by prepending a fake token to the text,
  * so that it uses only the CLI command rules. Then the parser invokes
  * an execution routine corresponding to the command, which either constructs
- * the whole reply and returns or (in case it expects the reply will be long)
+ * the whole reply and returns back or (in case it expects the reply will be long)
  * it prints a partial reply and asks the CLI module (using the @cont hook)
- * to call it again when the output will be transferred to the user.
+ * to call it again when the output is transferred to the user.
  *
  * The @this_cli variable points to a &cli structure of the session being
  * currently parsed, but it's of course available only in command handlers
diff --git a/nest/locks.c b/nest/locks.c
index c1f7331e..11489b77 100644
--- a/nest/locks.c
+++ b/nest/locks.c
@@ -15,14 +15,14 @@
  * occur only when the user specifies an invalid configuration and therefore
  * he deserves to get what he has asked for, but unfortunately they can also
  * arise legitimately when the daemon is reconfigured and there exists (although
- * for a short time period only) an old protocol being shut down and a new one
+ * for a short time period only) an old protocol instance being shut down and a new one
  * willing to start up on the same interface.
  *
  * The solution is very simple: when any protocol wishes to use a network port
- * or some other non-shareable resource, it asks the core to lock it and doesn't
+ * or some other non-shareable resource, it asks the core to lock it and it doesn't
  * use the resource until it's notified that it has acquired the lock.
  *
- * Object locks are represented by &object_lock which is in turn a kind of
+ * Object locks are represented by &object_lock structures which are in turn a kind of
  * resource. Lockable resources are uniquely determined by resource type
  * (%OBJLOCK_UDP for a UDP port etc.), IP address (usually a broadcast or
  * multicast address the port is bound to), port number and interface.
diff --git a/nest/neighbor.c b/nest/neighbor.c
index 89c19ba3..c6e2f734 100644
--- a/nest/neighbor.c
+++ b/nest/neighbor.c
@@ -20,17 +20,17 @@
  * The neighbor cache maintains a collection of neighbor entries. Each
  * entry represents one IP address corresponding to either our directly
  * connected neighbor or our own end of the link (when the scope of the
- * address is set to %SCOPE_HOST) together with data belonging to a
+ * address is set to %SCOPE_HOST) together with per-neighbor data belonging to a
  * single protocol.
  *
  * Active entries represent known neighbors and are stored in a hash
- * table (to allow fast retrieval based on IP address of the node) and
+ * table (to allow fast retrieval based on the IP address of the node) and
  * two linked lists: one global and one per-interface (allowing quick
  * processing of interface change events). Inactive entries exist only
  * when the protocol has explicitly requested it via the %NEF_STICKY
  * flag because it wishes to be notified when the node will again become
  * a neighbor. Such entries are enqueued in a special list which is walked
- * whenever an interface becomes up.
+ * whenever an interface changes its state to up.
  *
  * When a neighbor event occurs (a neighbor gets disconnected or a sticky
  * inactive neighbor becomes connected), the protocol hook neigh_notify()
diff --git a/nest/proto-hooks.c b/nest/proto-hooks.c
index 29be6972..4035fdd7 100644
--- a/nest/proto-hooks.c
+++ b/nest/proto-hooks.c
@@ -9,7 +9,7 @@
 /**
  * DOC: Protocol hooks
  *
- * Each protocol provides a rich set of hook functions referred to by pointers
+ * Each protocol can provide a rich set of hook functions referred to by pointers
  * in either the &proto or &protocol structure. They are called by the core whenever
  * it wants the protocol to perform some action or to notify the protocol about
  * any change of its environment. All of the hooks can be set to %NULL which means
diff --git a/nest/proto.sgml b/nest/proto.sgml
index 3478d93a..6e20269b 100644
--- a/nest/proto.sgml
+++ b/nest/proto.sgml
@@ -67,7 +67,7 @@ the following states:
 <p>Unless the protocol is in the <tt/PS_DOWN/ state, it can decide to change
 its state by calling the <func/proto_notify_state/ function.
 
-<p>At any time, the core code can ask the protocol to shut down by calling its stop() hook.
+<p>At any time, the core code can ask the protocol to shut itself down by calling its stop() hook.
 
 <p>The <em/core state machine/ takes care of the core view of protocol state.
 The states are traversed according to changes of the protocol state machine, but
diff --git a/nest/rt-fib.c b/nest/rt-fib.c
index 28f9fc1c..34d862e2 100644
--- a/nest/rt-fib.c
+++ b/nest/rt-fib.c
@@ -21,7 +21,7 @@
  * We use two-stage hashing where we calculate a 16-bit primary hash key independent
  * on hash table size and then we just divide the primary keys modulo table size
  * to get a real hash key used for determining the bucket containing the node.
- * The lists of nodes in each buckets are sorted according to the primary hash
+ * The lists of nodes in each bucket are sorted according to the primary hash
  * key, hence if we keep the total number of buckets to be a power of two,
  * re-hashing of the structure keeps the relative order of the nodes.
  *
@@ -400,7 +400,7 @@ fit_put(struct fib_iterator *i, struct fib_node *n)
  * @f: FIB to be checked
  *
  * This debugging function audits a FIB by checking its internal consistency.
- * Use when you suspect somebody from corrupting innocent data structures.
+ * Use when you suspect somebody of corrupting innocent data structures.
  */
 void
 fib_check(struct fib *f)
diff --git a/nest/rt-table.c b/nest/rt-table.c
index 51da7366..ce3bf452 100644
--- a/nest/rt-table.c
+++ b/nest/rt-table.c
@@ -16,7 +16,7 @@
  * There exist multiple routing tables (a primary one together with any
  * number of secondary ones if requested by the configuration). Each table
  * is basically a FIB containing entries describing the individual
- * destination networks. For each network (represented by structure &net)
+ * destination networks. For each network (represented by structure &net),
  * there is a one-way linked list of network entries (&rte), the first entry
  * on the list being the best possible one (i.e., the one we currently use
  * for routing), the order of the other ones is undetermined.
diff --git a/proto/bgp/bgp.c b/proto/bgp/bgp.c
index cc4c97ec..6bdb5fc0 100644
--- a/proto/bgp/bgp.c
+++ b/proto/bgp/bgp.c
@@ -21,7 +21,7 @@
  * many connections, but not too much and, which is more important, it makes
  * BGP much easier to implement.
  *
- * Each instance of BGP (corresponding to one BGP peer) is described by a &bgp_proto
+ * Each instance of BGP (corresponding to a single BGP peer) is described by a &bgp_proto
  * structure to which are attached individual connections represented by &bgp_connection
  * (usually, there exists only one connection, but during BGP session setup, there
  * can be more of them). The connections are handled according to the BGP state machine
@@ -39,7 +39,7 @@
  * immediately instead of sending both updates). There also exists a special bucket holding
  * all the route withdrawals which cannot be queued anywhere else as they don't have any
  * attributes. If we have any packet to send (due to either new routes or the connection
- * tracking code wanting to send a Open, KeepAlive or Notification message), we call
+ * tracking code wanting to send a Open, Keepalive or Notification message), we call
  * bgp_schedule_packet() which sets the corresponding bit in a @packet_to_send
  * bit field in &bgp_conn and as soon as the transmit socket buffer becomes empty,
  * we call bgp_fire_tx(). It inspects state of all the packet type bits and calls
diff --git a/proto/rip/rip.c b/proto/rip/rip.c
index 77cef776..242960c3 100644
--- a/proto/rip/rip.c
+++ b/proto/rip/rip.c
@@ -18,29 +18,30 @@
  */
 
 /**
- * DOC: Routing information protocol
+ * DOC: Routing Information Protocol
  *
- * Rip is pretty simple protocol so half of this code is interface
- * with core. We maintain our own linked list of &rip_entry -- it serves
- * as our small routing table. Rip never adds into this linked list at
- * packet reception; instead, it lets core know about data from packet,
- * and waits for core to call our rip_rte_notify.
+ * RIP is a pretty simple protocol, so about a half of its code is interface
+ * with the core.
  *
- * Within rip_tx(), this list is
- * walked, and packet is generated using rip_tx_prepare(). This gets
+ * We maintain our own linked list of &rip_entry structures -- it serves
+ * as our small routing table. RIP never adds to this linked list upon
+ * packet reception; instead, it lets the core know about data from the packet
+ * and waits for the core to call rip_rte_notify().
+ *
+ * Within rip_tx(), the list is
+ * walked and a packet is generated using rip_tx_prepare(). This gets
  * tricky because we may need to send more than one packet to one
- * destination. Struct &rip_connection is used to hold info such as how
- * many of &rip_entry's we already send, and is also used to protect
- * from two concurrent sends to one destination. Each &rip_interface has
+ * destination. Struct &rip_connection is used to hold context information such as how
+ * many of &rip_entry's we have already sent and it's also used to protect
+ * against two concurrent sends to one destination. Each &rip_interface has
  * at most one &rip_connection.
  *
  * We are not going to honor requests for sending part of
- * routing table. That would need to turn split horizon off,
- * etc.  
+ * routing table. That would need to turn split horizon off etc.  
  *
- * Triggered updates. RFC says: when triggered update was sent, don't send
- * new one for something between 1 and 5 seconds (and send one
- * after that). We do something else: once in 5 second
+ * About triggered updates, RFC says: when a triggered update was sent,
+ * don't send a new one for something between 1 and 5 seconds (and send one
+ * after that). We do something else: each 5 seconds,
  * we look for any changed routes and broadcast them.
  */
 
@@ -70,7 +71,7 @@ static struct rip_interface *new_iface(struct proto *p, struct iface *new, unsig
 #define P_NAME p->name
 
 /*
- * DOC: Output processing
+ * Output processing
  *
  * This part is responsible for getting packets out to the network.
  */
@@ -251,7 +252,7 @@ find_interface(struct proto *p, struct iface *what)
 }
 
 /*
- * DOC: Input processing
+ * Input processing
  *
  * This part is responsible for any updates that come from network 
  */
@@ -466,7 +467,7 @@ rip_rx(sock *s, int size)
 }
 
 /*
- * DOC: Interface to bird core
+ * Interface to BIRD core
  */
 
 static void
@@ -482,10 +483,10 @@ rip_dump_entry( struct rip_entry *e )
  * @t: timer
  *
  * Broadcast routing tables periodically (using rip_tx) and kill
- * routes that are too old. Rip keeps its own entries in main routing
- * table linked by link list (functions rip_rte_insert() and
- * rip_rte_delete() are responsible for that), walks this list in timer
- * and in case entry is too old, it is discarded.
+ * routes that are too old. RIP keeps a list of its own entries present
+ * in the core table by a linked list (functions rip_rte_insert() and
+ * rip_rte_delete() are responsible for that), it walks this list in the timer
+ * and in case an entry is too old, it is discarded.
  */
 
 static void
@@ -636,13 +637,13 @@ kill_iface(struct proto *p, struct rip_interface *i)
 /**
  * new_iface
  * @p: myself
- * @new: interface to be created or %NULL if we are creating magic
- * socket. Magic socket is used for listening, and is also used for
- * sending requested responses. 
+ * @new: interface to be created or %NULL if we are creating a magic
+ * socket. The magic socket is used for listening and also for
+ * sending requested responses.
  * @flags: interface flags
  * @patt: pattern this interface matched, used for access to config options
  *
- * actually create struct interface and start listening to it
+ * Create an interface structure and start listening on the interface.
  */
 static struct rip_interface *
 new_iface(struct proto *p, struct iface *new, unsigned long flags, struct iface_patt *patt )
diff --git a/sysdep/unix/io.c b/sysdep/unix/io.c
index f503bb99..445bc7ce 100644
--- a/sysdep/unix/io.c
+++ b/sysdep/unix/io.c
@@ -78,11 +78,11 @@ tracked_fopen(pool *p, char *name, char *mode)
  *
  * Timers are resources which represent a wish of a module to call
  * a function at the specified time. The platform dependent code
- * doesn't guarantee the exact timing, only that a timer function
+ * doesn't guarantee exact timing, only that a timer function
  * won't be called before the requested time.
  *
  * In BIRD, real time is represented by values of the &bird_clock_t type
- * which are integral numbers corresponding to a number of seconds since
+ * which are integral numbers interpreted as a number of seconds since
  * a fixed (but platform dependent) epoch. The current time can be read
  * from a variable @now with reasonable accuracy.
  *
diff --git a/sysdep/unix/krt.c b/sysdep/unix/krt.c
index 2b4117c7..317d3f58 100644
--- a/sysdep/unix/krt.c
+++ b/sysdep/unix/krt.c
@@ -26,14 +26,14 @@
  * separate KRT protocols which cooperate with each other  [Linux 2.2].
  * In this case, we keep only a single scan timer.
  *
- * We use FIB node flags to keep track of route synchronization status. We also
- * attach temporary &rte's to the routing tables, but it cannot harm the rest of
- * BIRD since table synchronization is an atomic process.
+ * We use FIB node flags in the routing table to keep track of route
+ * synchronization status. We also attach temporary &rte's to the routing table,
+ * but it cannot do any harm to the rest of BIRD since table synchronization is
+ * an atomic process.
  *
  * When starting up, we cheat by looking if there is another
  * KRT instance to be initialized later and performing table scan
- * only once for all the instances.
- */
+ * only once for all the instances.  */
 
 /*
  *  If you are brave enough, continue now.  You cannot say you haven't been warned.