Added library progdocs.

8 files changed, 427 insertions, 11 deletions

diff --git a/lib/Doc b/lib/Doc
index bf1b4060..a57516ef 100644
--- a/lib/Doc
+++ b/lib/Doc
@@ -1,12 +1,8 @@
-H Library
-S checksum.c md5.c
+H Library functions
 S ip.c ipv4.c ipv6.c
 S lists.c
-S bitops.c
-S patmatch.c
-S printf.c
-S unaligned.h
-H Resource management
+S checksum.c bitops.c patmatch.c printf.c xmalloc.c
+H Resources
 S resource.c
 S mempool.c
 S slab.c
diff --git a/lib/bitops.c b/lib/bitops.c
index 10bca047..6ca05050 100644
--- a/lib/bitops.c
+++ b/lib/bitops.c
@@ -9,12 +9,27 @@
 #include "nest/bird.h"
 #include "bitops.h"
 
+/**
+ * u32_mkmask - create a bit mask
+ * @n: number of bits
+ *
+ * u32_mkmask() returns an unsigned 32-bit integer which binary
+ * representation consists of @n ones followed by zeroes.
+ */
 u32
 u32_mkmask(unsigned n)
 {
   return n ? ~((1 << (32 - n)) - 1) : 0;
 }
 
+/**
+ * u32_masklen - calculate length of a bit mask
+ * @x: bit mask
+ *
+ * This function checks whether the given integer @x represents
+ * a valid bit mask (binary representation contains first ones, then
+ * zeroes) and returns the number of ones or -1 if the mask is invalid.
+ */
 int
 u32_masklen(u32 x)
 {
diff --git a/lib/checksum.c b/lib/checksum.c
index 94cf71e8..2ffc1770 100644
--- a/lib/checksum.c
+++ b/lib/checksum.c
@@ -1,11 +1,15 @@
 /*
  *	BIRD Library -- IP One-Complement Checksum
  *
- *	(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: Miscellaneous functions.
+ */
+
 #include <stdarg.h>
 
 #include "nest/bird.h"
@@ -83,6 +87,20 @@ ipsum_calc(void *frag, unsigned len, va_list args)
   return sum;
 }
 
+/**
+ * ipsum_verify - verify an IP checksum
+ * @frag: first packet fragment
+ * @len: length in bytes
+ *
+ * This function verifies whether a given fragmented packet
+ * has correct one's complement checksum as used by the IP
+ * protocol.
+ *
+ * It uses all the clever tricks described in RFC 1071 to speed
+ * up checksum calculation as much as possible.
+ *
+ * Result: 1 if the checksum is correct, 0 else.
+ */
 int
 ipsum_verify(void *frag, unsigned len, ...)
 {
@@ -95,6 +113,17 @@ ipsum_verify(void *frag, unsigned len, ...)
   return sum == 0xffff;
 }
 
+/**
+ * ipsum_calculate - compute an IP checksum
+ * @frag: first packet fragment
+ * @len: length in bytes
+ *
+ * This function caculates a one's complement checksum of a given fragmented
+ * packet.
+ *
+ * It uses all the clever tricks described in RFC 1071 to speed
+ * up checksum calculation as much as possible.
+ */
 u16
 ipsum_calculate(void *frag, unsigned len, ...)
 {
diff --git a/lib/ip.c b/lib/ip.c
index 25b4d103..79242906 100644
--- a/lib/ip.c
+++ b/lib/ip.c
@@ -1,7 +1,7 @@
 /*
  *	BIRD Library -- IP address routines common for IPv4 and IPv6
  *
- *	(c) 1998--1999 Martin Mares <mj@ucw.cz>
+ *	(c) 1998--2000 Martin Mares <mj@ucw.cz>
  *
  *	Can be freely distributed and used under the terms of the GNU GPL.
  */
@@ -9,6 +9,21 @@
 #include "nest/bird.h"
 #include "lib/ip.h"
 
+/**
+ * DOC: IP addresses
+ *
+ * BIRD uses its own abstraction of IP address in order to share the same
+ * code for both IPv4 and IPv6. IP addresses are represented as entities
+ * of type &ip_addr which are never to be treated as numbers and instead
+ * they should be manipulated using the following functions and macros.
+ */
+
+/**
+ * ip_scope_text - get texual representation of address scope
+ * @scope: scope (%SCOPE_xxx)
+ *
+ * Returns a pointer to a textual name of the scope given.
+ */
 char *
 ip_scope_text(unsigned scope)
 {
@@ -19,3 +34,228 @@ ip_scope_text(unsigned scope)
   else
     return scope_table[scope];
 }
+
+#if 0
+/**
+ * ipa_equal - compare two IP addresses for equality
+ * @x: IP address
+ * @y: IP address
+ *
+ * ipa_equal() returns 1 if @x and @y represent the same IP address, else 0.
+ */
+int ipa_equal(ip_addr x, ip_addr y) { DUMMY }
+
+/**
+ * ipa_nonzero - test if an IP address is defined
+ * @x: IP address
+ *
+ * ipa_nonzero returns 1 if @x is a defined IP address (not all bits are zero),
+ * else 0.
+ *
+ * The undefined all-zero address is reachable as a |IPA_NONE| macro.
+ */
+int ipa_nonzero(ip_addr x) { DUMMY }
+
+/**
+ * ipa_and - compute bitwise and of two IP addresses
+ * @x: IP address
+ * @y: IP address
+ *
+ * This function returns a bitwise and of @x and @y. It's primarily
+ * used for network masking.
+ */
+ip_addr ipa_and(ip_addr x, ip_addr y) { DUMMY }
+
+/**
+ * ipa_or - compute bitwise or of two IP addresses
+ * @x: IP address
+ * @y: IP address
+ *
+ * This function returns a bitwise or of @x and @y.
+ */
+ip_addr ipa_or(ip_addr x, ip_addr y) { DUMMY }
+
+/**
+ * ipa_xor - compute bitwise xor of two IP addresses
+ * @x: IP address
+ * @y: IP address
+ *
+ * This function returns a bitwise xor of @x and @y.
+ */
+ip_addr ipa_xor(ip_addr x, ip_addr y) { DUMMY }
+
+/**
+ * ipa_not - compute bitwise negation of two IP addresses
+ * @x: IP address
+ *
+ * This function returns a bitwise negation of @x.
+ */
+ip_addr ipa_not(ip_addr x) { DUMMY }
+
+/**
+ * ipa_mkmask - create a netmask
+ * @x: prefix length
+ *
+ * This function returns an &ip_addr corresponding of a netmask
+ * of an address prefix of size @x.
+ */
+ip_addr ipa_mkmask(int x) { DUMMY }
+
+/**
+ * ipa_mkmask - calculate netmask length
+ * @x: IP address
+ *
+ * This function checks whether @x represents a valid netmask and
+ * returns the size of the associate network prefix or -1 for invalid
+ * mask.
+ */
+int ipa_mklen(ip_addr x) { DUMMY }
+
+/**
+ * ipa_hash - hash IP addresses
+ * @x: IP address
+ *
+ * ipa_hash() returns a 16-bit hash value of the IP address @x.
+ */
+int ipa_hash(ip_addr x) { DUMMY }
+
+/**
+ * ipa_hton - convert IP address to network order
+ * @x: IP address
+ *
+ * Converts the IP address @x to the network byte order.
+ *
+ * Beware, this is a macro and it alters the argument!
+ */
+void ipa_hton(ip_addr x) { DUMMY }
+
+/**
+ * ipa_ntoh - convert IP address to host order
+ * @x: IP address
+ *
+ * Converts the IP address @x from the network byte order.
+ *
+ * Beware, this is a macro and it alters the argument!
+ */
+void ipa_ntoh(ip_addr x) { DUMMY }
+
+/**
+ * ipa_classify - classify an IP address
+ * @x: IP address
+ *
+ * ipa_classify() returns an address class of @x, that is a bitwise or
+ * of address type (%IADDR_INVALID, %IADDR_HOST, %IADDR_BROADCAST, %IADDR_MULTICAST)
+ * with adress scope (%SCOPE_HOST to %SCOPE_UNIVERSE) or -1 (%IADDR_INVALID)
+ * for an invalid address.
+ */
+int ipa_classify(ip_addr x) { DUMMY }
+
+/**
+ * ipa_opposite - return address of point-to-point neighbor
+ * @x: IP address of our end of the link
+ *
+ * ipa_opposite() returns an address of the opposite end of a numbered
+ * point-to-point link.
+ *
+ * This function is available in IPv4 version only.
+ */
+ip_addr ipa_opposite(ip_addr x) { DUMMY }
+
+/**
+ * ipa_class_mask - guess netmask according to address class
+ * @x: IP address
+ *
+ * This function (available in IPv4 version only) returns a
+ * network mask according to the address class of @x. Although
+ * classful addressing is nowadays obsolete, there still live
+ * routing protocols transferring no prefix lengths nor netmasks
+ * and this function could be useful to them.
+ */
+ip_addr ipa_classify(ip_addr x) { DUMMY }
+
+/**
+ * ipa_from_u32 - convert IPv4 address to an integer
+ * @x: IP address
+ *
+ * This function takes an IPv4 address and returns its numeric
+ * representation.
+ */
+u32 ipa_from_u32(ip_addr x) { DUMMY }
+
+/**
+ * ipa_to_u32 - convert integer to IPv4 address
+ * @x: a 32-bit integer
+ *
+ * ipa_to_u32() takes a numeric representation of an IPv4 address
+ * and converts it to the corresponding &ip_addr.
+ */
+ip_addr ipa_to_u32(u32 x) { DUMMY }
+
+/**
+ * ipa_compare - compare two IP addresses for order
+ * @x: IP address
+ * @y: IP address
+ *
+ * The ipa_compare() function takes two IP addresses and returns
+ * -1 if @x is less than @y in canonical ordering (lexicographical
+ * order of the bit strings), 1 if @x is greater than @y and 0
+ * if they are the same.
+ */
+int ipa_compare(ip_addr x, ip_addr y) { DUMMY }
+
+/**
+ * ipa_build - build an IPv6 address from parts
+ * @a1: part #1
+ * @a2: part #2
+ * @a3: part #3
+ * @a4: part #4
+ *
+ * ipa_build() takes @a1 to @a4 and assembles them to a single IPv6
+ * address. It's used for example when a protocol wants to bind its
+ * socket to a hard-wired multicast address.
+ */
+ip_addr ipa_build(u32 a1, u32 a2, u32 a3, u32 a4) { DUMMY }
+
+/**
+ * ipa_absolutize - convert link scope IPv6 address to universe scope
+ * @x: link scope IPv6 address
+ * @y: universe scope IPv6 prefix of the interface
+ *
+ * This function combines a link-scope IPv6 address @x with the universe
+ * scope prefix @x of the network assigned to an interface to get a
+ * universe scope form of @x.
+ */
+ip_addr ipa_absolutize(ip_addr x, ip_addr y) { DUMMY }
+
+/**
+ * ip_ntop - convert IP address to textual representation
+ * @a: IP address
+ * @buf: buffer of size at least %STD_ADDRESS_P_LENGTH
+ *
+ * This function takes an IP address and creates its textual
+ * representation for presenting to the user.
+ */
+char *ip_ntop(ip_addr a, char *buf) { DUMMY }
+
+/**
+ * ip_ntox - convert IP address to hexadecimal representation
+ * @a: IP address
+ * @buf: buffer of size at least %STD_ADDRESS_P_LENGTH
+ *
+ * This function takes an IP address and creates its hexadecimal
+ * textual representation. Primary use: debugging dumps.
+ */
+char *ip_ntox(ip_addr a, char *buf) { DUMMY }
+
+/**
+ * ip_pton - parse textual representation of IP address
+ * @a: textual representation
+ * @o: where to put the resulting address
+ *
+ * This function parses a textual IP address representation and
+ * stores the decoded address to a variable pointed to by @o.
+ * Returns 0 if a parse error has occured, else 0.
+ */
+int ip_pton(char *a, ip_addr *o) { DUMMY }
+
+#endif
diff --git a/lib/lists.c b/lib/lists.c
index c14eb4c7..6d97ff50 100644
--- a/lib/lists.c
+++ b/lib/lists.c
@@ -6,11 +6,36 @@
  *	Can be freely distributed and used under the terms of the GNU GPL.
  */
 
+/**
+ * DOC: Linked lists
+ *
+ * The BIRD library provides a set of functions for operating on linked
+ * lists. The lists are internally represented as standard doubly linked
+ * lists with synthetic head and tail which makes all the basic operations
+ * run in constant time and contain no extra end-of-list checks. Each list
+ * is described by a &list structure, nodes can have any format as long
+ * as they start with a &node structure. If you want your nodes to belong
+ * to multiple lists at once, you can embed multiple &node structures in them
+ * and use the SKIP_BACK() macro to calculate a pointer to the start of the
+ * structure from a &node pointer, but beware of obscurity.
+ *
+ * There also exist safe linked lists (&slist, &snode and all functions
+ * being prefixed with |s_|) which support asynchronous walking very
+ * similar to that used in the &fib structure.
+ */
+
 #define _BIRD_LISTS_C_
 
 #include "nest/bird.h"
 #include "lib/lists.h"
 
+/**
+ * add_tail - append a node to a list
+ * @l: linked list
+ * @n: list node
+ *
+ * add_tail() takes a node @n and appends it at the end of the list @l.
+ */
 LIST_INLINE void
 add_tail(list *l, node *n)
 {
@@ -22,6 +47,13 @@ add_tail(list *l, node *n)
   l->tail = n;
 }
 
+/**
+ * add_head - prepend a node to a list
+ * @l: linked list
+ * @n: list node
+ *
+ * add_head() takes a node @n and prepends it at the start of the list @l.
+ */
 LIST_INLINE void
 add_head(list *l, node *n)
 {
@@ -33,6 +65,14 @@ add_head(list *l, node *n)
   l->head = n;
 }
 
+/**
+ * insert_node - insert a node to a list
+ * @n: a new list node
+ * @after: a node of a list
+ *
+ * Inserts a node @n to a linked list after an already inserted
+ * node @after.
+ */
 LIST_INLINE void
 insert_node(node *n, node *after)
 {
@@ -44,6 +84,12 @@ insert_node(node *n, node *after)
   z->prev = n;
 }
 
+/**
+ * rem_node - remove a node from a list
+ * @n: node to be removed
+ *
+ * Removes a node @n from the list it's linked in.
+ */
 LIST_INLINE void
 rem_node(node *n)
 {
@@ -54,6 +100,13 @@ rem_node(node *n)
   x->prev = z;
 }
 
+/**
+ * init_list - create an empty list
+ * @l: list
+ *
+ * init_list() takes a &list structure and initializes its
+ * fields, so that it represents an empty list.
+ */
 LIST_INLINE void
 init_list(list *l)
 {
@@ -62,6 +115,14 @@ init_list(list *l)
   l->tail = (node *) &l->head;
 }
 
+/**
+ * add_tail_list - concatenate two lists
+ * @to: destination list
+ * @l: source list
+ *
+ * This function appends all elements of the list @l to
+ * the list @to in constant time.
+ */
 LIST_INLINE void
 add_tail_list(list *to, list *l)
 {
diff --git a/lib/patmatch.c b/lib/patmatch.c
index 15d5007a..923e8f86 100644
--- a/lib/patmatch.c
+++ b/lib/patmatch.c
@@ -1,7 +1,7 @@
 /*
  *	BIRD Library -- Generic Shell-Like Pattern Matching (currently only '?' and '*')
  *
- *	(c) 1998 Martin Mares, <mj@atrey.karlin.mff.cuni.cz>
+ *	(c) 1998--2000 Martin Mares <mj@ucw.cz>
  */
 
 #include "nest/bird.h"
@@ -52,3 +52,23 @@ MATCH_FUNC_NAME(byte *p, byte *s)
     }
   return !*s;
 }
+
+#if 0
+/**
+ * patmatch - match shell-like patterns
+ * @p: pattern
+ * @s: string
+ *
+ * patmatch() returns whether given string @s matches the given shell-like
+ * pattern @p. The patterns consist of characters (which are matched literally),
+ * question marks which match any single character, asterisks which match any
+ * (possibly empty) string of characters and backslashes which are used to
+ * escape any special characters and force them to be treated literally.
+ *
+ * The matching process is not optimized with respect to time, so please
+ * avoid using this function for complex patterns.
+ */
+int
+patmatch(byte *p, byte *s)
+{ DUMMY; }
+#endif
diff --git a/lib/printf.c b/lib/printf.c
index a668aeaf..4bcffe56 100644
--- a/lib/printf.c
+++ b/lib/printf.c
@@ -109,6 +109,23 @@ static char * number(char * str, long num, int base, int size, int precision,
 	return str;
 }
 
+/**
+ * bvsnprintf - BIRD's vsnprintf()
+ * @buf: destination buffer
+ * @size: size of the buffer
+ * @fmt: format string
+ * @args: a list of arguments to be formatted
+ *
+ * This functions acts like ordinary sprintf() except that it checks
+ * available space to avoid buffer overflows and it allows some more
+ * format specifiers: |%I| for formatting of IP addresses and |%M| for
+ * error messages (uses strerror() to translate @errno code to
+ * message text). On the other hand, it doesn't support floating
+ * point numbers.
+ *
+ * Result: number of characters of the output string or -1 if
+ * the buffer space was insufficient.
+ */
 int bvsnprintf(char *buf, int size, const char *fmt, va_list args)
 {
 	int len;
@@ -308,11 +325,31 @@ int bvsnprintf(char *buf, int size, const char *fmt, va_list args)
 	return str-buf;
 }
 
+/**
+ * bvsprintf - BIRD's vsprintf()
+ * @buf: buffer
+ * @fmt: format string
+ * @args: a list of arguments to be formatted
+ *
+ * This function is equivalent to bvsnprintf() with an infinite
+ * buffer size. Please use carefully only when you are absolutely
+ * sure the buffer won't overflow.
+ */
 int bvsprintf(char *buf, const char *fmt, va_list args)
 {
   return bvsnprintf(buf, 1000000000, fmt, args);
 }
 
+/**
+ * bsprintf - BIRD's sprintf()
+ * @buf: buffer
+ * @fmt: format string
+ *
+ * This function is equivalent to bvsnprintf() with an infinite
+ * buffer size and variable arguments instead of a &va_list.
+ * Please use carefully only when you are absolutely
+ * sure the buffer won't overflow.
+ */
 int bsprintf(char * buf, const char *fmt, ...)
 {
   va_list args;
@@ -324,6 +361,14 @@ int bsprintf(char * buf, const char *fmt, ...)
   return i;
 }
 
+/**
+ * bsnprintf - BIRD's snprintf()
+ * @buf: buffer
+ * @size: buffer size
+ * @fmt: format string
+ *
+ * This function is equivalent to bsnprintf() with variable arguments instead of a &va_list.
+ */
 int bsnprintf(char * buf, int size, const char *fmt, ...)
 {
   va_list args;
diff --git a/lib/xmalloc.c b/lib/xmalloc.c
index 2bec260c..369d4201 100644
--- a/lib/xmalloc.c
+++ b/lib/xmalloc.c
@@ -1,7 +1,7 @@
 /*
  *	BIRD Library -- malloc() With Checking
  *
- *	(c) 1998--1999 Martin Mares <mj@ucw.cz>
+ *	(c) 1998--2000 Martin Mares <mj@ucw.cz>
  *
  *	Can be freely distributed and used under the terms of the GNU GPL.
  */
@@ -13,6 +13,16 @@
 
 #ifndef HAVE_LIBDMALLOC
 
+/**
+ * xmalloc - malloc with checking
+ * @size: block size
+ *
+ * This function is equivalent to malloc() except that in case of
+ * failure it calls die() to quit the program instead of returning
+ * a %NULL pointer.
+ *
+ * Whereever possible, please use the memory resources instead.
+ */
 void *
 xmalloc(unsigned size)
 {