chiark / gitweb /
Doxygen file headers for most files
authorRichard Kettlewell <rjk@greenend.org.uk>
Sat, 25 Oct 2008 17:42:35 +0000 (18:42 +0100)
committerRichard Kettlewell <rjk@greenend.org.uk>
Sat, 25 Oct 2008 17:42:35 +0000 (18:42 +0100)
102 files changed:
cgi/login.c
clients/authorize.c
clients/authorize.h
clients/disorder.c
clients/disorderfm.c
clients/filename-bytes.c
disobedience/added.c
disobedience/choose-menu.c
disobedience/choose-search.c
disobedience/choose.h
disobedience/lookup.c
disobedience/popup.c
disobedience/popup.h
disobedience/queue-generic.c
disobedience/queue-generic.h
disobedience/queue-menu.c
disobedience/queue.c
disobedience/recent.c
lib/Makefile.am
lib/arcfour.c
lib/arcfour.h
lib/authhash.h
lib/basen.h
lib/charset.h
lib/client-common.c
lib/client-common.h
lib/defs.h
lib/event.h
lib/eventdist.c
lib/eventdist.h
lib/eventlog.c
lib/eventlog.h
lib/fprintf.c
lib/hash.c
lib/hash.h
lib/hex.h
lib/hostname.c
lib/hostname.h
lib/inputline.h
lib/kvp.c
lib/kvp.h
lib/log.h
lib/logfd.c
lib/logfd.h
lib/mem.h
lib/memgc.c
lib/printf.c
lib/printf.h
lib/queue.c
lib/queue.h
lib/regsub.c
lib/regsub.h
lib/rtp.h
lib/sendmail.c
lib/sendmail.h
lib/signame.c
lib/signame.h
lib/snprintf.c
lib/split.c
lib/split.h
lib/syscalls.c
lib/syscalls.h
lib/table.c
lib/table.h
lib/timeval.h
lib/trackdb-int.h
lib/trackname.c
lib/trackname.h
lib/trackorder.c
lib/tracksort.c
lib/unidata.c
lib/unidata.h
lib/vacopy.h
lib/vector.c
lib/version.c
lib/version.h
lib/xgetdate.c
plugins/exec.c
plugins/execraw.c
plugins/fs.c
plugins/mad.c
plugins/madshim.h
plugins/notify.c
plugins/shell.c
plugins/tracklength.c
scripts/make-unidata
server/api-server.c
server/api.c
server/dbupgrade.c
server/deadlock.c
server/disorder-server.h
server/disorderd.c
server/dump.c
server/exports.c
server/play.c
server/plugin.c
server/queue-ops.c
server/rescan.c
server/state.c
server/stats.c
server/trackname.c
tests/udplog.c

index d490151..a7a6dc0 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file cgi/login.c
+ * @brief Web login support
+ */
 #include "disorder-cgi.h"
 
 /** @brief Client used by CGI
index 6dced26..93fe3f4 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file clients/authorize.c
+ * @brief Create a new login
+ */
 
 #include "common.h"
 
index de73294..977e248 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file clients/authorize.h
+ * @brief Create a new login
+ */
 #ifndef AUTHORIZE_H
 #define AUTHORIZE_H
 
index b07ffa1..6ac27bc 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file clients/disorder.c
+ * @brief Command-line client
+ */
 
 #include "common.h"
 
index 63ff12d..07743f8 100644 (file)
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file clients/disorderfm.c
+ * @brief DisOrder file manager
+ *
+ * Intended to support encoding conversion, tag extraction, etc.  Not yet
+ * complete (and hasn't been worked on for ages).
+ */
 #include "common.h"
 
 #include <getopt.h>
index 8bba942..13eea19 100644 (file)
@@ -1,5 +1,6 @@
-/* Grotty program to print out the bytes making up filenames in some
- * directory */
+/** @file clients/filename-bytes.c
+ * @brief Print out raw bytes of filenames in a directory
+ */
 
 #include "common.h"
 
index 9f9058b..32628ac 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file disobedience/added.c
+ * @brief List of recently added tracks
+ */
 #include "disobedience.h"
 #include "popup.h"
 #include "queue-generic.h"
index a57e887..37167e7 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file disobedience/choose-menu.c
+ * @brief Popup menu for choose screen
+ */
 #include "disobedience.h"
 #include "popup.h"
 #include "choose.h"
index b06e9f9..1208f17 100644 (file)
@@ -16,7 +16,7 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 /** @file disobedience/choose-search.c
- * @brief Search support
+ * @brief Search support for Disobedience choose window
  */
 #include "disobedience.h"
 #include "choose.h"
index dea27b2..97f7095 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file disobedience/choose.h
+ * @brief Choose window for Disobedience
+ */
 #ifndef CHOOSE_H
 #define CHOOSE_H
 
index f160501..68939ae 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file disobedience/lookup.c
+ * @brief Disobedience server lookups and caching
+ */
 #include "disobedience.h"
 
 static int namepart_lookups_outstanding;
index 6504722..6613cfc 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file disobedience/popup.c
+ * @brief Disobedience popup menus
+ */
 #include "disobedience.h"
 #include "popup.h"
 
index dd5dfeb..9706e03 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file disobedience/popup.h
+ * @brief Disobedience popup menus
+ */
 #ifndef POPUP_H
 #define POPUP_H
 
index 1fd1a53..fe327ca 100644 (file)
@@ -16,7 +16,7 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 /** @file disobedience/queue-generic.c
- * @brief Queue widgets
+ * @brief Disobedience queue widgets
  *
  * This file provides contains code shared between all the queue-like
  * widgets - the queue, the recent list and the added tracks list.
index 9a493e8..b73d90a 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file disobedience/queue-generic.h
+ * @brief Disobedience queue widgets
+ */
 #ifndef QUEUE_GENERIC_H
 #define QUEUE_GENERIC_H
 
index 7ccee6c..8111205 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file disobedience/queue-menu.c
+ * @brief Disobedience queue widget popup menu
+ */
 #include "disobedience.h"
 #include "popup.h"
 #include "queue-generic.h"
index 0e65245..c19dbc9 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file disobedience/queue.c
+ * @brief Disobedience queue widget
+ */
 #include "disobedience.h"
 #include "popup.h"
 #include "queue-generic.h"
index 36a98d1..0923a6d 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file disobedience/recent.c
+ * @brief Disobedience recently-played widget
+ */
 #include "disobedience.h"
 #include "popup.h"
 #include "queue-generic.h"
index 9b50089..ef10c49 100644 (file)
@@ -106,7 +106,12 @@ versionstring.h: version-string ${top_srcdir}/scripts/text2c
 
 definitions.h: Makefile
        rm -f $@.new
-       echo "#define PKGLIBDIR \"${pkglibdir}\"" > $@.new
+       echo "/** @file lib/definitions.h" >> $@.new
+       echo " * @brief Definitions exported from makefile" >> $@.new
+       echo " *" >> $@.new
+       echo " * DO NOT EDIT." >> $@.new
+       echo " */" >> $@.new
+       echo "#define PKGLIBDIR \"${pkglibdir}\"" >> $@.new
        echo "#define PKGCONFDIR \"${sysconfdir}/\"PACKAGE" >> $@.new
        echo "#define PKGSTATEDIR \"${localstatedir}/\"PACKAGE" >> $@.new
        echo "#define PKGDATADIR \"${pkgdatadir}/\"" >> $@.new
index 42aaf2b..7d469d8 100644 (file)
  * 02110-1301, USA.
  *
  */
-
-/* Code from Libgcrypt adapted for gnulib by Simon Josefsson. */
-
-/*
+/** @file lib/arcfour.c
+ * @brief Arcfour (RC4-compatible) stream cipher implementation
+ *
+ * Code from Libgcrypt adapted for gnulib by Simon Josefsson.
+ *
  * For a description of the algorithm, see:
+ * 
  *   Bruce Schneier: Applied Cryptography. John Wiley & Sons, 1996.
  *   ISBN 0-471-11709-9. Pages 397 ff.
  */
index 0a9d75c..af6e941 100644 (file)
@@ -18,6 +18,9 @@
  * 02110-1301, USA.
  *
  */
+/** @file lib/arcfour.h
+ * @brief Arcfour (RC4-compatible) stream cipher implementation
+ */
 
 /* Code from Libgcrypt adapted for gnulib by Simon Josefsson. */
 
index df5b629..8604a13 100644 (file)
@@ -1,6 +1,6 @@
 /*
  * This file is part of DisOrder.
- * Copyright (C) 2004, 2006, 2007 Richard Kettlewell
+ * Copyright (C) 2004, 2006, 2007, 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
@@ -15,6 +15,7 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/authhash.h @brief The authorization hash */
 #ifndef AUTHHASH_H
 #define AUTHHASH_H
 
index 5a7b84b..717f2ea 100644 (file)
@@ -15,7 +15,7 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/basen.h @brief Arbitrary base conversion */
 #ifndef BASEN_H
 #define BASEN_H
 
index 4395aec..be2b05a 100644 (file)
@@ -1,4 +1,3 @@
-
 /*
  * This file is part of DisOrder.
  * Copyright (C) 2004, 2005, 2007, 2008 Richard Kettlewell
@@ -16,6 +15,7 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/charset.h @brief Character set conversion */
 #ifndef CHARSET_H
 #define CHARSET_H
 
index 946cab7..ced82e4 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/client-common.c
+ * @brief Common code to client APIs
+ */
 
 #include "common.h"
 
index 9bc90cf..736ac6f 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/client-common.h
+ * @brief Common code to client APIs
+ */
 
 #ifndef CLIENT_COMMON_H
 #define CLIENT_COMMON_H
index 4fe5c86..41b65ea 100644 (file)
@@ -15,7 +15,7 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/defs.h @brief Definitions chosen by configure */
 #ifndef DEFS_H
 #define DEFS_H
 
index 5b312a3..2838c41 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/event.h
+ * @brief DisOrder event loop
+ */
 #ifndef EVENT_H
 #define EVENT_H
 
index 66eae88..37893b6 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/eventdist.c
+ * @brief Event distribution
+ */
 #include "common.h"
 
 #include "mem.h"
index 7892391..367d816 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/eventdist.h
+ * @brief Event distribution
+ */
 #ifndef EVENTDIST_H
 #define EVENTDIST_H
 
index 9297906..a56884b 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/eventlog.c
+ * @brief Event logging
+ */
 #include "common.h"
 
 #include <stdarg.h>
index 236943e..87eea51 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/eventlog.h
+ * @brief Event logging
+ */
 #ifndef EVENTLOG_H
 #define EVENTLOG_H
 
index 812a931..b4de830 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/fprintf.c
+ * @brief UTF-8 workalike for fprintf() and vfprintf()
+ */
 
 #include "common.h"
 
index 64a48bb..d507d0a 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/hash.c
+ * @brief A simple hash table
+ */
 #include "common.h"
 
 #include "hash.h"
index 1577e03..e932f4b 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/hash.h
+ * @brief A simple hash table
+ */
 
 #ifndef HASH_H
 #define HASH_H
index e370240..1506219 100644 (file)
--- a/lib/hex.h
+++ b/lib/hex.h
@@ -15,6 +15,7 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/hex.h @brief Hexadecimal encoding and decoding */
 
 #ifndef HEX_H
 #define HEX_H
index 8e67d84..292b3ad 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/hostname.c
+ * @brief Get the local hostname
+ */
 
 #include "common.h"
 
index f8defd1..38808ee 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/hostname.h
+ * @brief Get the local hostname
+ */
 
 #ifndef HOSTNAME_H
 #define HOSTNAME_H
index c9a0449..a844194 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/inputline.h
+ * @brief Line input
+ */
 
 #ifndef INPUTLINE_H
 #define INPUTLINE_H
index 13a5cc4..748c47e 100644 (file)
--- a/lib/kvp.c
+++ b/lib/kvp.c
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/kvp.c
+ * @brief Linked list of key-value pairs
+ *
+ * Also supports URL encoding/decoding (of raw strings and kvp lists).
+ *
+ * For large sets of keys, see @ref lib/hash.c.
+ */
 
 #include "common.h"
 
index 7b41837..745304b 100644 (file)
--- a/lib/kvp.h
+++ b/lib/kvp.h
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/kvp.h
+ * @brief Linked list of key-value pairs
+ */
 
 #ifndef KVP_H
 #define KVP_H
index b512706..e7f6e43 100644 (file)
--- a/lib/log.h
+++ b/lib/log.h
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/log.h
+ * @brief Errors and logging
+ */
 
 #ifndef LOG_H
 #define LOG_H
index 7413379..a6f14c3 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/logfd.c
+ * @brief Redirect subprocess stderr to DisOrder server's log
+ */
 
 #include "common.h"
 
index 9cab2cb..ad43700 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/logfd.h
+ * @brief Redirect subprocess stderr to DisOrder server's log
+ */
 
 #ifndef LOGFD_H
 #define LOGFD_H
index 3ef4263..2aa70aa 100644 (file)
--- a/lib/mem.h
+++ b/lib/mem.h
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/mem.h
+ * @brief Memory management
+ */
 
 #ifndef MEM_H
 #define MEM_H
index 3df4621..4b7dabe 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/memgc.c
+ * @brief Memory management with garbage collection
+ */
 
 #define GC 1
 #include "mem.c"
index f227142..f921791 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/printf.c
+ * @brief UTF-8 *printf workalike (core)
+ */
 
 #define NO_MEMORY_ALLOCATION
 /* because byte_snprintf used from log.c */
index 0c7869e..9adb9ab 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/printf.h
+ * @brief UTF-8 *printf workalikes
+ */
 #ifndef PRINTF_H
 #define PRINTF_H
 
index cd11a50..71d85aa 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/queue.c
+ * @brief Track queues
+ */
 #include "common.h"
 
 #include <errno.h>
index ad70b34..a084502 100644 (file)
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/queue.h
+ * @brief Track queues
+ *
+ * Used for the queue, the recently played list and the currently playing
+ * track, both in the server and in clients.
+ */
 #ifndef QUEUE_H
 #define QUEUE_H
 
index aab20e2..cde61cf 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/regsub.c
+ * @brief Regexp substitution
+ */
 #include "common.h"
 
 #include <pcre.h>
index c4107e0..1a5aa43 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/regsub.h
+ * @brief Regexp substitution
+ */
 #ifndef REGSUB_H
 #define REGSUB_H
 
index 3ac14be..d0ab1ed 100644 (file)
--- a/lib/rtp.h
+++ b/lib/rtp.h
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/rtp.h
+ * @brief RTP packet header format
+ *
+ * See <a href="http://www.ietf.org/rfc/rfc1889.txt">RFC1889</a>.
+ */
 
 #ifndef RTP_H
 #define RTP_H
 
-/* RTP is defined in RFC1889 */
+/** @brief RTP packet header format
+ *
+ * See <a href="http://www.ietf.org/rfc/rfc1889.txt">RFC1889</a> (now obsoleted
+ * by <a href="http://www.ietf.org/rfc/rfc3550.txt">RFC3550</a>).
+ */
 struct attribute((packed)) rtp_header {
+  /** @brief Version, padding, extension and CSRC
+   *
+   * Version is bits 6 and 7; currently always 2.
+   *
+   * Padding is bit 5; if set frame includes padding octets.
+   *
+   * eXtension is bit 4; if set there is a header extension.
+   *
+   * CSRC Count is bits 0-3 and is the number of CSRC identifiers following the
+   * header.
+   */
   uint8_t vpxcc;
+
+  /** @brief Marker and payload type
+   *
+   * Marker is bit 7.  Profile-defined.
+   *
+   * Payload Type is bits 0-6.  Profile defined.  
+   */
   uint8_t mpt;
+
+  /** @brief Sequence number */
   uint16_t seq;
+
+  /** @brief Timestamp */
   uint32_t timestamp;
+
+  /** @brief Synchronization source */
   uint32_t ssrc;
 };
 
index b53a89f..5b9a82c 100644 (file)
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/sendmail.c
+ * @brief Sending email
+ *
+ * Can send email either via a local MTA or by connecting to an SMTP TCP port.
+ * The former is preferred as there is a strong implication that the local MTA
+ * will queue for you than some random TCP SMTP server you found.
+ */
 #include "common.h"
 
 #include <errno.h>
index 3852137..945dc25 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/sendmail.h
+ * @brief Sending email
+ */
 
 #ifndef SENDMAIL_H
 #define SENDMAIL_H
index 212ebee..27f9509 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/signame.c
+ * @brief Signal names
+ */
 #include "common.h"
 
 #include <signal.h>
@@ -132,6 +134,10 @@ static const struct sigtable {
 #undef S
 };
 
+/** @brief Map a signal name to its number
+ * @param s Signal name e.g. "SIGINT"
+ * @return Signal value or -1 if not found
+ */
 int find_signal(const char *s) {
   int n;
 
index 5c50fcf..0406681 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/signame.h
+ * @brief Signal names
+ */
 #ifndef SIGNAME_H
 #define SIGNAME_H
 
index 69bafc7..e62e3c9 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/snprintf.c
+ * @brief UTF-8 capable *snprintf workalikes
+ */
 
 #define NO_MEMORY_ALLOCATION
 /* because used from log.c */
index ebcf821..d4410dc 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/split.c
+ * @brief String splitting
+ */
 #include "common.h"
 
 #include <ctype.h>
index b2b99d5..7aee4b6 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/split.h
+ * @brief String splitting
+ */
 #ifndef SPLIT_H
 #define SPLIT_H
 
index 0415a2d..0d5dc18 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/syscalls.c
+ * @brief Error-checking library call wrappers
+ */
 #include "common.h"
 
 #include <unistd.h>
index 7031eac..9f8bd20 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/syscalls.h
+ * @brief Error-checking library call wrappers
+ */
 #ifndef SYSCALLS_H
 #define SYSCALLS_H
 
index 7295532..a646d92 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/table.c
+ * @brief Generic binary search
+ */
 #include "common.h"
 
 #include "table.h"
index 12c05c0..db237ac 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/table.h
+ * @brief Generic binary search
+ */
 #ifndef TABLE_H
 #define TABLE_H
 
index 2911dd4..930ad24 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/timeval.h
+ * @brief Arithmetic on timeval structures
+ */
 #ifndef TIMEVAL_H
 #define TIMEVAL_H
 
index cb00e14..6d5234e 100644 (file)
@@ -15,7 +15,8 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/trackdb-int.h
+ * @brief Track database internals */
 #ifndef TRACKDB_INT_H
 #define TRACKDB_INT_H
 
index 36e438f..fa40c3b 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/trackname.c
+ * @brief Track name calculation
+ */
 #include "common.h"
 
 #include <pcre.h>
index 31c7df8..63b881b 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/trackname.h
+ * @brief Track name calculation
+ */
 #ifndef TRACKNAME_H
 #define TRACKNAME_H
 
index df86e29..d0ae448 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/trackorder.c
+ * @brief Track ordering
+ */
 #include "common.h"
 
 #include <pcre.h>
index 5ae0d03..2f81739 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/tracksort.c
+ * @brief Track ordering
+ */
 #include "common.h"
 
 #include "trackname.h"
index db4334d..b22b5bc 100644 (file)
@@ -1,4 +1,10 @@
-/* Automatically generated file, see scripts/make-unidata */
+/** @file lib/unidata.c
+ * @brief Unicode tables
+ *
+ * Automatically generated file, see scripts/make-unidata
+ *
+ * DO NOT EDIT.
+ */
 #include "common.h"
 #include "unidata.h"
 #define Cc unicode_General_Category_Cc
index aa8814d..86f5fee 100644 (file)
@@ -1,4 +1,10 @@
-/* Automatically generated file, see scripts/make-unidata */
+/** @file lib/unidata.h
+ * @brief Unicode tables
+ *
+ * Automatically generated file, see scripts/make-unidata
+ *
+ * DO NOT EDIT.
+ */
 #ifndef UNIDATA_H
 #define UNIDATA_H
 enum unicode_General_Category {
index f933396..d152b36 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/vacopy.h
+ * @brief va_copy fixup
+ */
 #ifndef VACOPY_H
 #define VACOPY_H
 
index 6803a14..4d798f1 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/vector.c
+ * @brief Dynamic array utilities
+ */
 #include "common.h"
 
 #include <stddef.h>
index e591222..e4eb005 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file lib/version.c
+ * @brief Display version string and exit
+ */
 #include "common.h"
 
 #include "syscalls.h"
index 0b0a004..b8ee0d5 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file lib/version.h
+ * @brief Display version string and exit
+ */
 #ifndef VERSION_H
 #define VERSION_H
 
index 9d8b492..d3a3862 100644 (file)
@@ -1,7 +1,11 @@
-/* Derived from getdate.c in glibc 2.3.6.  This is pretty much
+/** @file lib/xgetdate.c
+ * @brief Date parsing
+ *
+ * Derived from getdate.c in glibc 2.3.6.  This is pretty much
  * standard getdate() except that you supply the template in an
  * argument, rather than messing around with environment variables and
- * files.  */
+ * files.
+ */
 
 /* Convert a string representation of time to a time value.
    Copyright (C) 1997,1998,1999,2000,2001,2003 Free Software Foundation, Inc.
index 6efc2bf..f6ed8b3 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file plugins/exec.c
+ * @brief Plugin to play a track by executing a command
+ */
 #include <config.h>
 
 #include <unistd.h>
index c967fda..8af8c61 100644 (file)
@@ -1,3 +1,8 @@
+/** @file plugins/execraw.c
+ * @brief Plugin to play a track by executing a command (raw mode)
+ *
+ * Shares code with @ref exec.c.
+ */
 #define TYPE DISORDER_PLAYER_RAW
 #include "exec.c"
 
index 9e857f9..1099d14 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file plugins/fs.c
+ * @brief Plugin to find tracks in a filesystem
+ */
 #include <config.h>
 
 #include <string.h>
index 1e40325..005c3e6 100644 (file)
@@ -1,5 +1,9 @@
-/* This file is a subset of the debian source tarball of mpg321-0.2.10.3/mad.c
-   - see http://mpg321.sourceforge.net/ */
+/** @file plugins/mad.c
+ * @brief MP3 Length calculation
+ *
+ * This file is a subset of the debian source tarball of
+ * mpg321-0.2.10.3/mad.c - see http://mpg321.sourceforge.net/
+ */
 
 /*
     mpg321 - a fully free clone of mpg123.
index 83a709b..5d73611 100644 (file)
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file plugins/madshim.h
+ * @brief Integrate code from mpg123
+ */
 
 #ifndef MADSHIM_H
 #define MADSHIM_H
 
-/* shim to integrate code from mpg123 */
-
 typedef struct {
   int num_frames;
   mad_timer_t duration;
index 8f9dc80..a0d7c11 100644 (file)
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file plugins/notify.c
+ * @brief Standard notify plugin
+ *
+ * The arrangements here are not very satisfactory - you wanted to be
+ * able to replace the plugin but still keep its features.  So you
+ * wanted a list of plugins really.
+ */
 
 #include "common.h"
 
index 90cb4ac..bbd7a4e 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file plugins/shell.c
+ * @brief Plugin to execute track players via the shell.
+ */
 
 #include <config.h>
 
index 21b7fae..86a1fc8 100644 (file)
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file plugins/tracklength.c
+ * @brief Plugin to compute track lengths
+ *
+ * Currently implements MP3, OGG, FLAC and WAV.
+ */
 
 #include <config.h>
 
index e0b7b6a..d1490cc 100755 (executable)
@@ -336,7 +336,13 @@ while(<>) {
 print STDERR "Generating unidata.h...\n";
 open(STDOUT, ">unidata.h") or die "unidata.h: $!\n";
 
-out("/* Automatically generated file, see scripts/make-unidata */\n",
+out("/** \@file lib/unidata.h\n",
+    " * \@brief Unicode tables\n",
+    " *\n",
+    " * Automatically generated file, see scripts/make-unidata\n",
+    " *\n",
+    " * DO NOT EDIT.\n",
+    " */\n",
     "#ifndef UNIDATA_H\n",
     "#define UNIDATA_H\n");
 
@@ -436,7 +442,13 @@ close STDOUT or die "unidata.h: $!\n";
 print STDERR "Generating unidata.c...\n";
 open(STDOUT, ">unidata.c") or die "unidata.c: $!\n";
 
-out("/* Automatically generated file, see scripts/make-unidata */\n",
+out("/** \@file lib/unidata.c\n",
+    " * \@brief Unicode tables\n",
+    " *\n",
+    " * Automatically generated file, see scripts/make-unidata\n",
+    " *\n",
+    " * DO NOT EDIT.\n",
+    " */\n",
     "#include \"common.h\"\n",
     "#include \"unidata.h\"\n");
 
index ce5e123..bfd8923 100644 (file)
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file server/api-server.c
+ * @brief Server API functions
+ *
+ * These functions are made available to server-side plugins.
+ */
 
 #include "disorder-server.h"
 
index e5783c1..fe9686c 100644 (file)
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file server/api.c
+ * @brief Generic API
+ *
+ * These functions are made available to all kinds of plugins.
+ */
 #include "disorder-server.h"
 
 /* shared implementation of vararg functions */
index e89cd4e..bd08eed 100644 (file)
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file server/dbupgrade.c
+ * @brief Database upgrade utility
+ *
+ * Invoked by the server when necessary.
+ */
 #include "disorder-server.h"
 
 static DB_TXN *global_tid;
index b53bbd5..3c13351 100644 (file)
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file server/deadlock.c
+ * @brief Deadlock monitor
+ *
+ * Spawned by the server.
+ */
 #include "disorder-server.h"
 
 static const struct option options[] = {
index c3a0e69..09eafbc 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file server/disorder-server.h
+ * @brief Definitions for server and allied utilities
+ */
 
 #ifndef DISORDER_SERVER_H
 #define DISORDER_SERVER_H
index 10ff89b..e03fa42 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file server/disorderd.c
+ * @brief Main DisOrder server
+ */
 #include "disorder-server.h"
 
 static ev_source *ev;
index af1d43d..e08b32f 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file server/dump.c
+ * @brief Dump and restore database contents
+ */
 #include "disorder-server.h"
 
 static const struct option options[] = {
index 1a0bb7e..fb8426f 100644 (file)
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file server/exports.c
+ * @brief Server exports
+ *
+ * Force functions to be included in the server so they can be exported
+ * to plugins.
+ */
 #include "disorder.h"
 
 typedef void (*fptr)(void);
index 2889e42..f657d6f 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file server/play.c
+ * @brief Playing tracks
+ */
 
 #include "disorder-server.h"
 #include <ao/ao.h>
index 2032d9d..6695d5a 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file server/plugin.c
+ * @brief Server plugin interface
+ */
 #include "disorder-server.h"
 
 #include <dlfcn.h>
index fd883aa..01987a2 100644 (file)
@@ -15,6 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file server/queue-ops.c
+ * @brief Track queues (server-specific code)
+ */
 #include "disorder-server.h"
 
 static int find_in_list(struct queue_entry *needle,
index f779d02..1380e24 100644 (file)
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file server/rescan.c
+ * @brief Rescanning utility
+ *
+ * Invoked by the server.
+ */
 #include "disorder-server.h"
 
 static time_t last_report;
index f23c06c..a99474e 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file server/state.c
+ * @brief Global server state
+ */
 #include "disorder-server.h"
 
 static const char *current_unix;
index 772be13..81c92f4 100644 (file)
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** @file server/stats.c
+ * @brief Generate server statistics
+ *
+ * This is done in a subprogram because it can be quite slow and we don't want
+ * to wedge the rest of the server for the duration.
+ */
 
 #include "disorder-server.h"
 
index 116fed5..ec84f68 100644 (file)
@@ -15,7 +15,9 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/** @file server/trackname.c
+ * @brief Utility to run the track name calculator in isolation
+ */
 #include "disorder-server.h"
 
 static const struct option options[] = {
index f8839c8..a27252c 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  * USA
  */
-
+/** @file tests/udplog.c
+ * @brief UDP logging utility
+ *
+ * Intended for low-level debugging.
+ */
 #include "common.h"
 
 #include <getopt.h>