More documentation.

3 files changed, 167 insertions, 3 deletions

diff --git a/nest/Doc b/nest/Doc
index 626b3bd..7395e75 100644
--- a/nest/Doc
+++ b/nest/Doc
@@ -5,7 +5,7 @@ S rt-attr.c
 D prog-proto.sgml
 S proto.c
 S proto-hooks.c
+S iface.c
 S neighbor.c
-#S cli.c
-#S iface.c
+S cli.c
 S locks.c
diff --git a/nest/cli.c b/nest/cli.c
index ec18bc9..c575bfa 100644
--- a/nest/cli.c
+++ b/nest/cli.c
@@ -1,11 +1,54 @@
 /*
  *	BIRD Internet Routing Daemon -- Command-Line Interface
  *
- *	(c) 1999 Martin Mares <mj@ucw.cz>
+ *	(c) 1999--2000 Martin Mares <mj@ucw.cz>
  *
  *	Can be freely distributed and used under the terms of the GNU GPL.
  */
 
+/**
+ * DOC: Command line interface
+ *
+ * This module takes care of the BIRD's command-line interface (CLI).
+ * The CLI exists to provide a way to control BIRD remotely and to inspect
+ * its status. It uses a very simple textual protocol over a stream
+ * connection provided by the platform dependent code (on UNIX systems,
+ * it's a UNIX domain socket).
+ *
+ * Each session of the CLI consists of a sequence of request and replies,
+ * slightly resembling the FTP and SMTP protocols.
+ * Requests are commands encoded as a single line of text, replies are
+ * sequences of lines starting with a four-digit code followed by either
+ * a space (if it's the last line of the reply) or a minus sign (when the
+ * reply is going to continue with the next line), the rest of the line
+ * contains a textual message semantics of which depends on the numeric
+ * code. If a reply line has the same code as the previous one and it's
+ * 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,
+ * 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
+ * on the current state of command processing.
+ *
+ * The CLI commands are declared as a part of the configuration grammar
+ * by using the CF_CLI() macro. When a command is received, it's processed
+ * by the same lexical analyser and parser as used for the configuration, but
+ * 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)
+ * 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.
+ *
+ * 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
+ * not entered using the @cont hook.
+ */
+
 #include "nest/bird.h"
 #include "nest/cli.h"
 #include "conf/conf.h"
@@ -41,6 +84,24 @@ cli_alloc_out(cli *c, int size)
   return o->wpos - size;
 }
 
+/**
+ * cli_printf - send reply to a CLI connection
+ * @c: CLI connection
+ * @code: numeric code of the reply, negative for continuation lines
+ * @msg: a printf()-like formatting string.
+ *
+ * This function send a single line of reply to a given CLI connection.
+ * In works in all aspects like bsprintf() except that it automatically
+ * prepends the reply line prefix.
+ *
+ * Please note that if the connection can be already busy sending some
+ * data in which case cli_printf() stores the output to a temporary buffer,
+ * so please avoid sending a large batch of replies without waiting
+ * for the buffers to be flushed.
+ *
+ * If you want to write to the current CLI output, you can use the cli_msg()
+ * macro instead.
+ */
 void
 cli_printf(cli *c, int code, char *msg, ...)
 {
@@ -320,6 +381,12 @@ cli_free(cli *c)
   rfree(c->pool);
 }
 
+/**
+ * cli_init - initialize the CLI module
+ *
+ * This function is called during BIRD startup to initialize
+ * the internal data structures of the CLI module.
+ */
 void
 cli_init(void)
 {
diff --git a/nest/iface.c b/nest/iface.c
index 16961bf..e6adc08 100644
--- a/nest/iface.c
+++ b/nest/iface.c
@@ -6,6 +6,23 @@
  *	Can be freely distributed and used under the terms of the GNU GPL.
  */
 
+/**
+ * DOC: Interfaces
+ *
+ * The interface module keeps track of all network interfaces in the
+ * system and their addresses.
+ *
+ * Each interface is represented by an &iface structure which carries
+ * interface capability flags (%IF_MULTIACCESS, %IF_BROADCAST etc.),
+ * MTU, interface name and index and finally a linked list of network
+ * prefixes assigned to the interface, each one represented by
+ * struct &ifa.
+ *
+ * The interface module keeps a `soft-up' state for each &iface which
+ * is a conjunction of link being up, the interface being of a `sane'
+ * type and at least one IP address assigned to it.
+ */
+
 #undef LOCAL_DEBUG
 
 #include "nest/bird.h"
@@ -22,6 +39,12 @@ static void auto_router_id(void);
 
 list iface_list;
 
+/**
+ * ifa_dump - dump interface address
+ * @a: interface address descriptor
+ *
+ * This function dumps contents of an &ifa to the debug output.
+ */
 void
 ifa_dump(struct ifa *a)
 {
@@ -31,6 +54,13 @@ ifa_dump(struct ifa *a)
 	(a->flags & IA_UNNUMBERED) ? " UNNUM" : "");
 }
 
+/**
+ * if_dump - dump interface
+ * @i: interface to dump
+ *
+ * This function dumps all information associated with a given
+ * network interface to the debug output.
+ */
 void
 if_dump(struct iface *i)
 {
@@ -65,6 +95,12 @@ if_dump(struct iface *i)
     }
 }
 
+/**
+ * if_dump_all - dump all interfaces
+ *
+ * This function dumps information about all known network
+ * interfaces to the debug output.
+ */
 void
 if_dump_all(void)
 {
@@ -200,6 +236,22 @@ if_change_flags(struct iface *i, unsigned flags)
     if_notify_change((i->flags & IF_UP) ? IF_CHANGE_UP : IF_CHANGE_DOWN, i);
 }
 
+/**
+ * if_update - update interface status
+ * @new: new interface status
+ *
+ * if_update() is called by the low-level platform dependent code
+ * whenever it notices an interface change.
+ *
+ * There exist two types of interface updates: synchronous and asynchronous
+ * ones. In the synchronous case, the low-level code calls if_start_update(),
+ * scans all interfaces reported by the OS, uses if_update() and ifa_update()
+ * to pass them to the core and then it finishes the update sequence by
+ * calling if_end_update(). When working asynchronously, the sysdep code
+ * calls if_update() and ifa_update() whenever it notices a change.
+ *
+ * if_update() will automatically notify all other modules about the change.
+ */
 struct iface *
 if_update(struct iface *new)
 {
@@ -284,6 +336,13 @@ if_end_update(void)
     }
 }
 
+/**
+ * if_feed_baby - advertise interfaces to a new protocol
+ * @p: protocol to feed
+ *
+ * When a new protocol starts, this function sends it a series
+ * of notifications about all existing interfaces.
+ */
 void
 if_feed_baby(struct proto *p)
 {
@@ -302,6 +361,14 @@ if_feed_baby(struct proto *p)
     }
 }
 
+/**
+ * if_find_by_index - find interface by ifindex
+ * @idx: ifindex
+ *
+ * This function finds an &iface structure corresponding to an interface
+ * of the given index @idx. Returns a pointer to the structure or %NULL
+ * if no such structure exists.
+ */
 struct iface *
 if_find_by_index(unsigned idx)
 {
@@ -313,6 +380,14 @@ if_find_by_index(unsigned idx)
   return NULL;
 }
 
+/**
+ * if_find_by_name - find interface by name
+ * @name: interface name
+ *
+ * This function finds an &iface structure corresponding to an interface
+ * of the given name @name. Returns a pointer to the structure or %NULL
+ * if no such structure exists.
+ */
 struct iface *
 if_find_by_name(char *name)
 {
@@ -347,6 +422,14 @@ ifa_recalc_primary(struct iface *i)
   return res;
 }
 
+/**
+ * ifa_update - update interface address
+ * @a: new interface address
+ *
+ * This function adds address information to a network
+ * interface. It's called by the platform dependent code during
+ * the interface update process described under if_update().
+ */
 struct ifa *
 ifa_update(struct ifa *a)
 {
@@ -388,6 +471,14 @@ ifa_update(struct ifa *a)
   return b;
 }
 
+/**
+ * ifa_delete - remove interface address
+ * @a: interface address
+ *
+ * This function removes address information from a network
+ * interface. It's called by the platform dependent code during
+ * the interface update process described under if_update().
+ */
 void
 ifa_delete(struct ifa *a)
 {
@@ -434,6 +525,12 @@ auto_router_id(void)
 #endif
 }
 
+/**
+ * if_init - initialize interface module
+ *
+ * This function is called during BIRD startup to initialize
+ * all data structures of the interface module.
+ */
 void
 if_init(void)
 {