From 0590cedca75c01811972b2f694f60f24028ee973 Mon Sep 17 00:00:00 2001 Message-Id: <0590cedca75c01811972b2f694f60f24028ee973.1714795814.git.mdw@distorted.org.uk> From: Mark Wooding Date: Sun, 20 Jan 2008 15:54:47 +0000 Subject: [PATCH] A bit more doxygenization. Organization: Straylight/Edgeware From: Richard Kettlewell --- README.developers | 27 +++++++++++++++++++++------ lib/addr.c | 10 +++++++++- lib/base64.c | 2 +- lib/client.c | 13 +++++++++++-- lib/mime.c | 2 +- lib/sendmail.c | 2 +- lib/trackdb.c | 2 +- server/daemonize.c | 14 +++++++++++++- server/daemonize.h | 3 +++ 9 files changed, 61 insertions(+), 14 deletions(-) diff --git a/README.developers b/README.developers index 9e73d01..3302f5a 100644 --- 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 - 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. @@ -118,7 +121,8 @@ The Server: 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. @@ -141,13 +145,24 @@ Disobedience: * 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 - 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. diff --git a/lib/addr.c b/lib/addr.c index a763321..ec245c6 100644 --- 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)); } +/** @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); } @@ -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; @@ -160,6 +163,7 @@ static inline char *format_sockaddr4(const struct sockaddr_in *sin4) { return r; } +/** @brief Format an IPv6 address */ 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; } +/** @brief Format a UNIX socket address */ 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: diff --git a/lib/base64.c b/lib/base64.c index d794182..d4ba61f 100644 --- 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 - * @param table Table of characters to use * @return Decoded data * * See 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 + * @param table Table of characters to use * @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 08d325a..c06bdf1 100644 --- a/lib/client.c +++ b/lib/client.c @@ -59,12 +59,20 @@ #include "rights.h" #include "trackdb.h" +/** @brief Client handle contents */ 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; + /** @brief Username */ char *user; + /** @brief Report errors to @c stderr */ int verbose; - char *last; /* last error string */ + /** @brief Last error string */ + char *last; }; /** @brief Create a new client @@ -547,6 +555,7 @@ int disorder_playing(disorder_client *c, struct queue_entry **qp) { 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; diff --git a/lib/mime.c b/lib/mime.c index 880fe12..78a8bd3 100644 --- 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 - * @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, diff --git a/lib/sendmail.c b/lib/sendmail.c index b2f606c..f7b0155 100644 --- 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 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 */ diff --git a/lib/trackdb.c b/lib/trackdb.c index 3f4aee9..8945ec3 100644 --- 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 - * @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; diff --git a/server/daemonize.c b/server/daemonize.c index 5c3bbba..fe275d6 100644 --- a/server/daemonize.c +++ b/server/daemonize.c @@ -1,6 +1,6 @@ /* * 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 @@ -17,6 +17,9 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file server/daemonize.c + * @brief Go into background + */ #include @@ -31,6 +34,15 @@ #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; diff --git a/server/daemonize.h b/server/daemonize.h index 155b9b4..398cc79 100644 --- a/server/daemonize.h +++ b/server/daemonize.h @@ -17,6 +17,9 @@ * 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 -- [mdw]