A bit more doxygenization.

diff --git a/README.developers b/README.developers
index 9e73d01084f0d1cb660018b43d5528850348c72f..3302f5ad71444f1358d6feff8fdf19502ac8e5da 100644 (file)
--- a/README.developers
+++ b/README.developers
@@ -65,10 +65,13 @@ APIs And Formats:
 The Server:
 
    * The server's command implementations must not block.  Waiting for a little
 The Server:
 
    * The server's command implementations must not block.  Waiting for a little

-     disk IO is OK but blocking on long-lasting transactions or external
-     resources is not acceptable.  Long-running subprocesses should use
-     subprograms (rather than forking but not execing) if reasonably possible;
-     see c_stats() for an example.  c_reminder() is probably in the grey area.
+     disk IO is OK but blocking for extended periods on long-lasting
+     transactions or external resources is not acceptable; it will wedge the
+     server for all other users.
+
+     Long-running subprocesses should use subprograms (rather than forking but
+     not execing) if reasonably possible; see c_stats() for an example.
+     c_reminder() is probably in the grey area.

 
    * The server process does not use threads and I would like to keep it that
      way.
 
    * The server process does not use threads and I would like to keep it that
      way.


@@ -118,7 +121,8 @@ The Server:
 Web Interface:
 
    * The web interface does not use Javascript or Flash and I would like to
 Web Interface:
 
    * The web interface does not use Javascript or Flash and I would like to

-     keep it that way.
+     keep it that way.  Clever use of CSS is OK provided it works well on the
+     mainstream browsers.

 
    * I know that the web template syntax is rather nasty.  Perhaps it will be
      improved in a future version.
 
    * I know that the web template syntax is rather nasty.  Perhaps it will be
      improved in a future version.


@@ -141,13 +145,24 @@ Disobedience:
 
    * Update doc/disobedience.1.in for any changes you make.
 
 
    * Update doc/disobedience.1.in for any changes you make.
 

+New Platforms:
+
+   * It is not mandatory to have an entry in configure's 'case $host' section,
+     but may well be convenient.
+
+   * Complete support for a new platform implies updating scripts/setup.in and
+     scripts/teardown.in as well as getting the software to build and work (but
+     this doesn't mean that patches that don't achieve this will be rejected).
+

 Code And Patches:
 
    * Please follow the existing layout conventions.
 
    * Please try to write doc comments for new functions, types, etc using the
      same syntax as the existing ones.  Doxygen can be used to turn this into
 Code And Patches:
 
    * Please follow the existing layout conventions.
 
    * Please try to write doc comments for new functions, types, etc using the
      same syntax as the existing ones.  Doxygen can be used to turn this into

-     reference documentation.
+     reference documentation (see http://www.stack.nl/~dimitri/doxygen/) but
+     really the point is to have good inline code documentation, not the
+     Doxygen output as such.

 
    * More importantly, new configuration directives, protocol commands,
      interface features etc should be documented in the relevant places.
 
    * More importantly, new configuration directives, protocol commands,
      interface features etc should be documented in the relevant places.

diff --git a/lib/addr.c b/lib/addr.c
index a7633219853043c6d03443052578b4dd31ed2f31..ec245c6369788e981801b67a420667ce4c71392a 100644 (file)
--- a/lib/addr.c
+++ b/lib/addr.c
@@ -125,10 +125,12 @@ int addrinfocmp(const struct addrinfo *a,
   }
 }
 
   }
 }
 

+/** @brief Return nonzero if @p sin4 is an IPv4 multicast address */

 static inline int multicast4(const struct sockaddr_in *sin4) {
   return IN_MULTICAST(ntohl(sin4->sin_addr.s_addr));
 }
 
 static inline int multicast4(const struct sockaddr_in *sin4) {
   return IN_MULTICAST(ntohl(sin4->sin_addr.s_addr));
 }
 

+/** @brief Return nonzero if @p sin6 is an IPv6 multicast address */

 static inline int multicast6(const struct sockaddr_in6 *sin6) {
   return IN6_IS_ADDR_MULTICAST(&sin6->sin6_addr);
 }
 static inline int multicast6(const struct sockaddr_in6 *sin6) {
   return IN6_IS_ADDR_MULTICAST(&sin6->sin6_addr);
 }


@@ -145,6 +147,7 @@ int multicast(const struct sockaddr *sa) {
   }
 }
 
   }
 }
 

+/** @brief Format an IPv4 address */

 static inline char *format_sockaddr4(const struct sockaddr_in *sin4) {
   char buffer[1024], *r;
 
 static inline char *format_sockaddr4(const struct sockaddr_in *sin4) {
   char buffer[1024], *r;
 


@@ -160,6 +163,7 @@ static inline char *format_sockaddr4(const struct sockaddr_in *sin4) {
   return r;
 }
 
   return r;
 }
 

+/** @brief Format an IPv6 address */

 static inline char *format_sockaddr6(const struct sockaddr_in6 *sin6) {
   char buffer[1024], *r;
 
 static inline char *format_sockaddr6(const struct sockaddr_in6 *sin6) {
   char buffer[1024], *r;
 


@@ -175,11 +179,15 @@ static inline char *format_sockaddr6(const struct sockaddr_in6 *sin6) {
   return r;
 }
 
   return r;
 }
 

+/** @brief Format a UNIX socket address */

 static inline char *format_sockaddrun(const struct sockaddr_un *sun) {
   return xstrdup(sun->sun_path);
 }
     
 static inline char *format_sockaddrun(const struct sockaddr_un *sun) {
   return xstrdup(sun->sun_path);
 }
     

-/** @brief Construct a text description a sockaddr */
+/** @brief Construct a text description a sockaddr
+ * @param sa Socket address
+ * @return Human-readable form of address
+ */

 char *format_sockaddr(const struct sockaddr *sa) {
   switch(sa->sa_family) {
   case AF_INET:
 char *format_sockaddr(const struct sockaddr *sa) {
   switch(sa->sa_family) {
   case AF_INET:

diff --git a/lib/base64.c b/lib/base64.c
index d7941828380ac4ff9f4b8b0171a695532264644c..d4ba61f03d87a7a965d319a15c9e709d36528af0 100644 (file)
--- a/lib/base64.c
+++ b/lib/base64.c
@@ -38,7 +38,6 @@ static const char mime_base64_table[] =
 /** @brief Convert MIME base64
  * @param s base64 data
  * @param nsp Where to store length of converted data
 /** @brief Convert MIME base64
  * @param s base64 data
  * @param nsp Where to store length of converted data

- * @param table Table of characters to use

  * @return Decoded data
  *
  * See <a href="http://tools.ietf.org/html/rfc2045#section-6.8">RFC
  * @return Decoded data
  *
  * See <a href="http://tools.ietf.org/html/rfc2045#section-6.8">RFC


@@ -51,6 +50,7 @@ char *mime_base64(const char *s, size_t *nsp) {
 /** @brief Convert base64
  * @param s base64 data
  * @param nsp Where to store length of converted data
 /** @brief Convert base64
  * @param s base64 data
  * @param nsp Where to store length of converted data

+ * @param table Table of characters to use

  * @return Decoded data
  *
  * @p table should consist of 65 characters.  The first 64 will be used to
  * @return Decoded data
  *
  * @p table should consist of 65 characters.  The first 64 will be used to

diff --git a/lib/client.c b/lib/client.c
index 08d325a669276bbbc32478a669ab0205107b4f5d..c06bdf1617a04587ff0bad706a8689843a98ce69 100644 (file)
--- a/lib/client.c
+++ b/lib/client.c
@@ -59,12 +59,20 @@
 #include "rights.h"
 #include "trackdb.h"
 
 #include "rights.h"
 #include "trackdb.h"
 

+/** @brief Client handle contents */

 struct disorder_client {
 struct disorder_client {

-  FILE *fpin, *fpout;
+  /** @brief Stream to read from */
+  FILE *fpin;
+  /** @brief Stream to write to */
+  FILE *fpout;
+  /** @brief Peer description */

   char *ident;
   char *ident;

+  /** @brief Username */

   char *user;
   char *user;

+  /** @brief Report errors to @c stderr */

   int verbose;
   int verbose;

-  char *last;                          /* last error string */
+  /** @brief Last error string */
+  char *last;

 };
 
 /** @brief Create a new client
 };
 
 /** @brief Create a new client


@@ -547,6 +555,7 @@ int disorder_playing(disorder_client *c, struct queue_entry **qp) {
   return 0;
 }
 
   return 0;
 }
 

+/** @brief Fetch the queue, recent list, etc */

 static int disorder_somequeue(disorder_client *c,
                              const char *cmd, struct queue_entry **qp) {
   struct queue_entry *qh, **qt = &qh, *q;
 static int disorder_somequeue(disorder_client *c,
                              const char *cmd, struct queue_entry **qp) {
   struct queue_entry *qh, **qt = &qh, *q;

diff --git a/lib/mime.c b/lib/mime.c
index 880fe12c9c07326f67f5676df3c9734977bfb6ac..78a8bd36f181deec957c352b74f5a1e9ad5893f7 100644 (file)
--- a/lib/mime.c
+++ b/lib/mime.c
@@ -718,7 +718,7 @@ char *mime_to_qp(const char *text) {
  * @param text Underlying UTF-8 text
  * @param charsetp Where to store charset string
  * @param encodingp Where to store encoding string
  * @param text Underlying UTF-8 text
  * @param charsetp Where to store charset string
  * @param encodingp Where to store encoding string

- * @return Encoded text (might be @ref text)
+ * @return Encoded text (might be @p text)

  */
 const char *mime_encode_text(const char *text,
                             const char **charsetp,
  */
 const char *mime_encode_text(const char *text,
                             const char **charsetp,

diff --git a/lib/sendmail.c b/lib/sendmail.c
index b2f606c5e6138ba70e97cd5675b700de61f4d7a6..f7b0155a74c686afffcbe017a18f8687e2fafb5a 100644 (file)
--- a/lib/sendmail.c
+++ b/lib/sendmail.c
@@ -103,7 +103,7 @@ static int sendcommand(const char *tag, FILE *out, const char *fmt, ...) {
  * @param recipient Recipient address
  * @param subject Subject string
  * @param encoding Body encoding
  * @param recipient Recipient address
  * @param subject Subject string
  * @param encoding Body encoding

- * @param body_type Content-type of body
+ * @param content_type Content-type of body

  * @param body Text of body (encoded, but \n for newline)
  * @return 0 on success, non-0 on error
  */
  * @param body Text of body (encoded, but \n for newline)
  * @return 0 on success, non-0 on error
  */

diff --git a/lib/trackdb.c b/lib/trackdb.c
index 3f4aee9295258d0688937a63dc17b79aa3510c07..8945ec3a3f6538328934881ff1cfd0a4bceaa7d3 100644 (file)
--- a/lib/trackdb.c
+++ b/lib/trackdb.c
@@ -2167,7 +2167,7 @@ static int reap_rescan(ev_source attribute((unused)) *ev,
 
 /** @brief Initiate a rescan
  * @param ev Event loop or 0 to block
 
 /** @brief Initiate a rescan
  * @param ev Event loop or 0 to block

- * @param check 1 to recheck lengths, 0 to suppress check
+ * @param recheck 1 to recheck lengths, 0 to suppress check

  */
 void trackdb_rescan(ev_source *ev, int recheck) {
   int w;
  */
 void trackdb_rescan(ev_source *ev, int recheck) {
   int w;

diff --git a/server/daemonize.c b/server/daemonize.c
index 5c3bbba49ad5a944abca4e03b5dcf11d2933dd69..fe275d6354d576add39259a4c911ad74b4d6b7ce 100644 (file)
--- a/server/daemonize.c
+++ b/server/daemonize.c
@@ -1,6 +1,6 @@
 /*
  * This file is part of DisOrder.
 /*
  * This file is part of DisOrder.

- * Copyright (C) 2004, 2005 Richard Kettlewell
+ * Copyright (C) 2004, 2005, 2008 Richard Kettlewell

  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by


@@ -17,6 +17,9 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  * USA
  */
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  * USA
  */

+/** @file server/daemonize.c
+ * @brief Go into background
+ */

 
 #include <config.h>
 
 
 #include <config.h>
 


@@ -31,6 +34,15 @@
 #include "syscalls.h"
 #include "log.h"
 
 #include "syscalls.h"
 #include "log.h"
 

+/** @brief Go into background
+ * @param tag Message tag, or NULL
+ * @param fac Logging facility
+ * @param pidfile Where to store PID, or NULL
+ *
+ * Become a daemon.  stdout/stderr are lost and DisOrder's logging is
+ * redirected to syslog.  It is assumed that there are no FDs beyond 2
+ * that need closing.
+ */

 void daemonize(const char *tag, int fac, const char *pidfile) {
   pid_t pid, r;
   int w, dn;
 void daemonize(const char *tag, int fac, const char *pidfile) {
   pid_t pid, r;
   int w, dn;

diff --git a/server/daemonize.h b/server/daemonize.h
index 155b9b462c761888a04230a1ab9496a00cc0dc4c..398cc79f7c69d6f1f166bdf9f75b6c69c7017491 100644 (file)
--- a/server/daemonize.h
+++ b/server/daemonize.h
@@ -17,6 +17,9 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  * USA
  */
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  * USA
  */

+/** @file server/daemonize.h
+ * @brief Go into background
+ */

 
 #ifndef DAEMONIZE_H
 #define DAEMONIZE_H
 
 #ifndef DAEMONIZE_H
 #define DAEMONIZE_H