From 132a5a4a47f9dbc7c52ee15234d70258c59ccf8e Mon Sep 17 00:00:00 2001 Message-Id: <132a5a4a47f9dbc7c52ee15234d70258c59ccf8e.1714662928.git.mdw@distorted.org.uk> From: Mark Wooding Date: Sat, 25 Oct 2008 18:42:35 +0100 Subject: [PATCH] Doxygen file headers for most files Organization: Straylight/Edgeware From: Richard Kettlewell --- cgi/login.c | 4 +++- clients/authorize.c | 3 +++ clients/authorize.h | 3 +++ clients/disorder.c | 3 +++ clients/disorderfm.c | 7 ++++++- clients/filename-bytes.c | 5 +++-- disobedience/added.c | 3 +++ disobedience/choose-menu.c | 3 +++ disobedience/choose-search.c | 2 +- disobedience/choose.h | 3 +++ disobedience/lookup.c | 3 +++ disobedience/popup.c | 3 +++ disobedience/popup.h | 3 +++ disobedience/queue-generic.c | 2 +- disobedience/queue-generic.h | 3 +++ disobedience/queue-menu.c | 3 +++ disobedience/queue.c | 3 +++ disobedience/recent.c | 3 +++ lib/Makefile.am | 7 ++++++- lib/arcfour.c | 10 ++++++---- lib/arcfour.h | 3 +++ lib/authhash.h | 3 ++- lib/basen.h | 2 +- lib/charset.h | 2 +- lib/client-common.c | 3 +++ lib/client-common.h | 3 +++ lib/defs.h | 2 +- lib/event.h | 4 +++- lib/eventdist.c | 4 +++- lib/eventdist.h | 4 +++- lib/eventlog.c | 4 +++- lib/eventlog.h | 4 +++- lib/fprintf.c | 3 +++ lib/hash.c | 4 +++- lib/hash.h | 3 +++ lib/hex.h | 1 + lib/hostname.c | 3 +++ lib/hostname.h | 3 +++ lib/inputline.h | 3 +++ lib/kvp.c | 7 +++++++ lib/kvp.h | 3 +++ lib/log.h | 3 +++ lib/logfd.c | 3 +++ lib/logfd.h | 3 +++ lib/mem.h | 3 +++ lib/memgc.c | 3 +++ lib/printf.c | 3 +++ lib/printf.h | 3 +++ lib/queue.c | 4 +++- lib/queue.h | 7 ++++++- lib/regsub.c | 4 +++- lib/regsub.h | 4 +++- lib/rtp.h | 35 ++++++++++++++++++++++++++++++++++- lib/sendmail.c | 8 +++++++- lib/sendmail.h | 3 +++ lib/signame.c | 8 +++++++- lib/signame.h | 4 +++- lib/snprintf.c | 3 +++ lib/split.c | 4 +++- lib/split.h | 3 +++ lib/syscalls.c | 4 +++- lib/syscalls.h | 4 +++- lib/table.c | 4 +++- lib/table.h | 4 +++- lib/timeval.h | 4 +++- lib/trackdb-int.h | 3 ++- lib/trackname.c | 4 +++- lib/trackname.h | 4 +++- lib/trackorder.c | 4 +++- lib/tracksort.c | 3 +++ lib/unidata.c | 8 +++++++- lib/unidata.h | 8 +++++++- lib/vacopy.h | 4 +++- lib/vector.c | 4 +++- lib/version.c | 4 +++- lib/version.h | 3 +++ lib/xgetdate.c | 8 ++++++-- plugins/exec.c | 4 +++- plugins/execraw.c | 5 +++++ plugins/fs.c | 4 +++- plugins/mad.c | 8 ++++++-- plugins/madshim.h | 5 +++-- plugins/notify.c | 7 +++++++ plugins/shell.c | 3 +++ plugins/tracklength.c | 5 +++++ scripts/make-unidata | 16 ++++++++++++++-- server/api-server.c | 5 +++++ server/api.c | 6 +++++- server/dbupgrade.c | 5 +++++ server/deadlock.c | 6 +++++- server/disorder-server.h | 3 +++ server/disorderd.c | 3 +++ server/dump.c | 4 +++- server/exports.c | 7 ++++++- server/play.c | 3 +++ server/plugin.c | 4 +++- server/queue-ops.c | 3 +++ server/rescan.c | 6 +++++- server/state.c | 4 +++- server/stats.c | 6 ++++++ server/trackname.c | 4 +++- tests/udplog.c | 6 +++++- 102 files changed, 398 insertions(+), 63 deletions(-) diff --git a/cgi/login.c b/cgi/login.c index d490151..a7a6dc0 100644 --- a/cgi/login.c +++ b/cgi/login.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file cgi/login.c + * @brief Web login support + */ #include "disorder-cgi.h" /** @brief Client used by CGI diff --git a/clients/authorize.c b/clients/authorize.c index 6dced26..93fe3f4 100644 --- a/clients/authorize.c +++ b/clients/authorize.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file clients/authorize.c + * @brief Create a new login + */ #include "common.h" diff --git a/clients/authorize.h b/clients/authorize.h index de73294..977e248 100644 --- a/clients/authorize.h +++ b/clients/authorize.h @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file clients/authorize.h + * @brief Create a new login + */ #ifndef AUTHORIZE_H #define AUTHORIZE_H diff --git a/clients/disorder.c b/clients/disorder.c index b07ffa1..6ac27bc 100644 --- a/clients/disorder.c +++ b/clients/disorder.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file clients/disorder.c + * @brief Command-line client + */ #include "common.h" diff --git a/clients/disorderfm.c b/clients/disorderfm.c index 63ff12d..07743f8 100644 --- a/clients/disorderfm.c +++ b/clients/disorderfm.c @@ -15,7 +15,12 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @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 diff --git a/clients/filename-bytes.c b/clients/filename-bytes.c index 8bba942..13eea19 100644 --- a/clients/filename-bytes.c +++ b/clients/filename-bytes.c @@ -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" diff --git a/disobedience/added.c b/disobedience/added.c index 9f9058b..32628ac 100644 --- a/disobedience/added.c +++ b/disobedience/added.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file disobedience/added.c + * @brief List of recently added tracks + */ #include "disobedience.h" #include "popup.h" #include "queue-generic.h" diff --git a/disobedience/choose-menu.c b/disobedience/choose-menu.c index a57e887..37167e7 100644 --- a/disobedience/choose-menu.c +++ b/disobedience/choose-menu.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file disobedience/choose-menu.c + * @brief Popup menu for choose screen + */ #include "disobedience.h" #include "popup.h" #include "choose.h" diff --git a/disobedience/choose-search.c b/disobedience/choose-search.c index b06e9f9..1208f17 100644 --- a/disobedience/choose-search.c +++ b/disobedience/choose-search.c @@ -16,7 +16,7 @@ * along with this program. If not, see . */ /** @file disobedience/choose-search.c - * @brief Search support + * @brief Search support for Disobedience choose window */ #include "disobedience.h" #include "choose.h" diff --git a/disobedience/choose.h b/disobedience/choose.h index dea27b2..97f7095 100644 --- a/disobedience/choose.h +++ b/disobedience/choose.h @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file disobedience/choose.h + * @brief Choose window for Disobedience + */ #ifndef CHOOSE_H #define CHOOSE_H diff --git a/disobedience/lookup.c b/disobedience/lookup.c index f160501..68939ae 100644 --- a/disobedience/lookup.c +++ b/disobedience/lookup.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file disobedience/lookup.c + * @brief Disobedience server lookups and caching + */ #include "disobedience.h" static int namepart_lookups_outstanding; diff --git a/disobedience/popup.c b/disobedience/popup.c index 6504722..6613cfc 100644 --- a/disobedience/popup.c +++ b/disobedience/popup.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file disobedience/popup.c + * @brief Disobedience popup menus + */ #include "disobedience.h" #include "popup.h" diff --git a/disobedience/popup.h b/disobedience/popup.h index dd5dfeb..9706e03 100644 --- a/disobedience/popup.h +++ b/disobedience/popup.h @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file disobedience/popup.h + * @brief Disobedience popup menus + */ #ifndef POPUP_H #define POPUP_H diff --git a/disobedience/queue-generic.c b/disobedience/queue-generic.c index 1fd1a53..fe327ca 100644 --- a/disobedience/queue-generic.c +++ b/disobedience/queue-generic.c @@ -16,7 +16,7 @@ * along with this program. If not, see . */ /** @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. diff --git a/disobedience/queue-generic.h b/disobedience/queue-generic.h index 9a493e8..b73d90a 100644 --- a/disobedience/queue-generic.h +++ b/disobedience/queue-generic.h @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file disobedience/queue-generic.h + * @brief Disobedience queue widgets + */ #ifndef QUEUE_GENERIC_H #define QUEUE_GENERIC_H diff --git a/disobedience/queue-menu.c b/disobedience/queue-menu.c index 7ccee6c..8111205 100644 --- a/disobedience/queue-menu.c +++ b/disobedience/queue-menu.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file disobedience/queue-menu.c + * @brief Disobedience queue widget popup menu + */ #include "disobedience.h" #include "popup.h" #include "queue-generic.h" diff --git a/disobedience/queue.c b/disobedience/queue.c index 0e65245..c19dbc9 100644 --- a/disobedience/queue.c +++ b/disobedience/queue.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file disobedience/queue.c + * @brief Disobedience queue widget + */ #include "disobedience.h" #include "popup.h" #include "queue-generic.h" diff --git a/disobedience/recent.c b/disobedience/recent.c index 36a98d1..0923a6d 100644 --- a/disobedience/recent.c +++ b/disobedience/recent.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file disobedience/recent.c + * @brief Disobedience recently-played widget + */ #include "disobedience.h" #include "popup.h" #include "queue-generic.h" diff --git a/lib/Makefile.am b/lib/Makefile.am index 9b50089..ef10c49 100644 --- a/lib/Makefile.am +++ b/lib/Makefile.am @@ -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 diff --git a/lib/arcfour.c b/lib/arcfour.c index 42aaf2b..7d469d8 100644 --- a/lib/arcfour.c +++ b/lib/arcfour.c @@ -18,11 +18,13 @@ * 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. */ diff --git a/lib/arcfour.h b/lib/arcfour.h index 0a9d75c..af6e941 100644 --- a/lib/arcfour.h +++ b/lib/arcfour.h @@ -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. */ diff --git a/lib/authhash.h b/lib/authhash.h index df5b629..8604a13 100644 --- a/lib/authhash.h +++ b/lib/authhash.h @@ -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 . */ +/** @file lib/authhash.h @brief The authorization hash */ #ifndef AUTHHASH_H #define AUTHHASH_H diff --git a/lib/basen.h b/lib/basen.h index 5a7b84b..717f2ea 100644 --- a/lib/basen.h +++ b/lib/basen.h @@ -15,7 +15,7 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/basen.h @brief Arbitrary base conversion */ #ifndef BASEN_H #define BASEN_H diff --git a/lib/charset.h b/lib/charset.h index 4395aec..be2b05a 100644 --- a/lib/charset.h +++ b/lib/charset.h @@ -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 . */ +/** @file lib/charset.h @brief Character set conversion */ #ifndef CHARSET_H #define CHARSET_H diff --git a/lib/client-common.c b/lib/client-common.c index 946cab7..ced82e4 100644 --- a/lib/client-common.c +++ b/lib/client-common.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file lib/client-common.c + * @brief Common code to client APIs + */ #include "common.h" diff --git a/lib/client-common.h b/lib/client-common.h index 9bc90cf..736ac6f 100644 --- a/lib/client-common.h +++ b/lib/client-common.h @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file lib/client-common.h + * @brief Common code to client APIs + */ #ifndef CLIENT_COMMON_H #define CLIENT_COMMON_H diff --git a/lib/defs.h b/lib/defs.h index 4fe5c86..41b65ea 100644 --- a/lib/defs.h +++ b/lib/defs.h @@ -15,7 +15,7 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/defs.h @brief Definitions chosen by configure */ #ifndef DEFS_H #define DEFS_H diff --git a/lib/event.h b/lib/event.h index 5b312a3..2838c41 100644 --- a/lib/event.h +++ b/lib/event.h @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/event.h + * @brief DisOrder event loop + */ #ifndef EVENT_H #define EVENT_H diff --git a/lib/eventdist.c b/lib/eventdist.c index 66eae88..37893b6 100644 --- a/lib/eventdist.c +++ b/lib/eventdist.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/eventdist.c + * @brief Event distribution + */ #include "common.h" #include "mem.h" diff --git a/lib/eventdist.h b/lib/eventdist.h index 7892391..367d816 100644 --- a/lib/eventdist.h +++ b/lib/eventdist.h @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/eventdist.h + * @brief Event distribution + */ #ifndef EVENTDIST_H #define EVENTDIST_H diff --git a/lib/eventlog.c b/lib/eventlog.c index 9297906..a56884b 100644 --- a/lib/eventlog.c +++ b/lib/eventlog.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/eventlog.c + * @brief Event logging + */ #include "common.h" #include diff --git a/lib/eventlog.h b/lib/eventlog.h index 236943e..87eea51 100644 --- a/lib/eventlog.h +++ b/lib/eventlog.h @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/eventlog.h + * @brief Event logging + */ #ifndef EVENTLOG_H #define EVENTLOG_H diff --git a/lib/fprintf.c b/lib/fprintf.c index 812a931..b4de830 100644 --- a/lib/fprintf.c +++ b/lib/fprintf.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file lib/fprintf.c + * @brief UTF-8 workalike for fprintf() and vfprintf() + */ #include "common.h" diff --git a/lib/hash.c b/lib/hash.c index 64a48bb..d507d0a 100644 --- a/lib/hash.c +++ b/lib/hash.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/hash.c + * @brief A simple hash table + */ #include "common.h" #include "hash.h" diff --git a/lib/hash.h b/lib/hash.h index 1577e03..e932f4b 100644 --- a/lib/hash.h +++ b/lib/hash.h @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file lib/hash.h + * @brief A simple hash table + */ #ifndef HASH_H #define HASH_H diff --git a/lib/hex.h b/lib/hex.h index e370240..1506219 100644 --- 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 . */ +/** @file lib/hex.h @brief Hexadecimal encoding and decoding */ #ifndef HEX_H #define HEX_H diff --git a/lib/hostname.c b/lib/hostname.c index 8e67d84..292b3ad 100644 --- a/lib/hostname.c +++ b/lib/hostname.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file lib/hostname.c + * @brief Get the local hostname + */ #include "common.h" diff --git a/lib/hostname.h b/lib/hostname.h index f8defd1..38808ee 100644 --- a/lib/hostname.h +++ b/lib/hostname.h @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file lib/hostname.h + * @brief Get the local hostname + */ #ifndef HOSTNAME_H #define HOSTNAME_H diff --git a/lib/inputline.h b/lib/inputline.h index c9a0449..a844194 100644 --- a/lib/inputline.h +++ b/lib/inputline.h @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file lib/inputline.h + * @brief Line input + */ #ifndef INPUTLINE_H #define INPUTLINE_H diff --git a/lib/kvp.c b/lib/kvp.c index 13a5cc4..748c47e 100644 --- a/lib/kvp.c +++ b/lib/kvp.c @@ -15,6 +15,13 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @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" diff --git a/lib/kvp.h b/lib/kvp.h index 7b41837..745304b 100644 --- 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 . */ +/** @file lib/kvp.h + * @brief Linked list of key-value pairs + */ #ifndef KVP_H #define KVP_H diff --git a/lib/log.h b/lib/log.h index b512706..e7f6e43 100644 --- 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 . */ +/** @file lib/log.h + * @brief Errors and logging + */ #ifndef LOG_H #define LOG_H diff --git a/lib/logfd.c b/lib/logfd.c index 7413379..a6f14c3 100644 --- a/lib/logfd.c +++ b/lib/logfd.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file lib/logfd.c + * @brief Redirect subprocess stderr to DisOrder server's log + */ #include "common.h" diff --git a/lib/logfd.h b/lib/logfd.h index 9cab2cb..ad43700 100644 --- a/lib/logfd.h +++ b/lib/logfd.h @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file lib/logfd.h + * @brief Redirect subprocess stderr to DisOrder server's log + */ #ifndef LOGFD_H #define LOGFD_H diff --git a/lib/mem.h b/lib/mem.h index 3ef4263..2aa70aa 100644 --- 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 . */ +/** @file lib/mem.h + * @brief Memory management + */ #ifndef MEM_H #define MEM_H diff --git a/lib/memgc.c b/lib/memgc.c index 3df4621..4b7dabe 100644 --- a/lib/memgc.c +++ b/lib/memgc.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file lib/memgc.c + * @brief Memory management with garbage collection + */ #define GC 1 #include "mem.c" diff --git a/lib/printf.c b/lib/printf.c index f227142..f921791 100644 --- a/lib/printf.c +++ b/lib/printf.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file lib/printf.c + * @brief UTF-8 *printf workalike (core) + */ #define NO_MEMORY_ALLOCATION /* because byte_snprintf used from log.c */ diff --git a/lib/printf.h b/lib/printf.h index 0c7869e..9adb9ab 100644 --- a/lib/printf.h +++ b/lib/printf.h @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file lib/printf.h + * @brief UTF-8 *printf workalikes + */ #ifndef PRINTF_H #define PRINTF_H diff --git a/lib/queue.c b/lib/queue.c index cd11a50..71d85aa 100644 --- a/lib/queue.c +++ b/lib/queue.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/queue.c + * @brief Track queues + */ #include "common.h" #include diff --git a/lib/queue.h b/lib/queue.h index ad70b34..a084502 100644 --- a/lib/queue.h +++ b/lib/queue.h @@ -15,7 +15,12 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @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 diff --git a/lib/regsub.c b/lib/regsub.c index aab20e2..cde61cf 100644 --- a/lib/regsub.c +++ b/lib/regsub.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/regsub.c + * @brief Regexp substitution + */ #include "common.h" #include diff --git a/lib/regsub.h b/lib/regsub.h index c4107e0..1a5aa43 100644 --- a/lib/regsub.h +++ b/lib/regsub.h @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/regsub.h + * @brief Regexp substitution + */ #ifndef REGSUB_H #define REGSUB_H diff --git a/lib/rtp.h b/lib/rtp.h index 3ac14be..d0ab1ed 100644 --- a/lib/rtp.h +++ b/lib/rtp.h @@ -15,16 +15,49 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file lib/rtp.h + * @brief RTP packet header format + * + * See RFC1889. + */ #ifndef RTP_H #define RTP_H -/* RTP is defined in RFC1889 */ +/** @brief RTP packet header format + * + * See RFC1889 (now obsoleted + * by RFC3550). + */ 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; }; diff --git a/lib/sendmail.c b/lib/sendmail.c index b53a89f..5b9a82c 100644 --- a/lib/sendmail.c +++ b/lib/sendmail.c @@ -15,7 +15,13 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @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 diff --git a/lib/sendmail.h b/lib/sendmail.h index 3852137..945dc25 100644 --- a/lib/sendmail.h +++ b/lib/sendmail.h @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file lib/sendmail.h + * @brief Sending email + */ #ifndef SENDMAIL_H #define SENDMAIL_H diff --git a/lib/signame.c b/lib/signame.c index 212ebee..27f9509 100644 --- a/lib/signame.c +++ b/lib/signame.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/signame.c + * @brief Signal names + */ #include "common.h" #include @@ -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; diff --git a/lib/signame.h b/lib/signame.h index 5c50fcf..0406681 100644 --- a/lib/signame.h +++ b/lib/signame.h @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/signame.h + * @brief Signal names + */ #ifndef SIGNAME_H #define SIGNAME_H diff --git a/lib/snprintf.c b/lib/snprintf.c index 69bafc7..e62e3c9 100644 --- a/lib/snprintf.c +++ b/lib/snprintf.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file lib/snprintf.c + * @brief UTF-8 capable *snprintf workalikes + */ #define NO_MEMORY_ALLOCATION /* because used from log.c */ diff --git a/lib/split.c b/lib/split.c index ebcf821..d4410dc 100644 --- a/lib/split.c +++ b/lib/split.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/split.c + * @brief String splitting + */ #include "common.h" #include diff --git a/lib/split.h b/lib/split.h index b2b99d5..7aee4b6 100644 --- a/lib/split.h +++ b/lib/split.h @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file lib/split.h + * @brief String splitting + */ #ifndef SPLIT_H #define SPLIT_H diff --git a/lib/syscalls.c b/lib/syscalls.c index 0415a2d..0d5dc18 100644 --- a/lib/syscalls.c +++ b/lib/syscalls.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/syscalls.c + * @brief Error-checking library call wrappers + */ #include "common.h" #include diff --git a/lib/syscalls.h b/lib/syscalls.h index 7031eac..9f8bd20 100644 --- a/lib/syscalls.h +++ b/lib/syscalls.h @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/syscalls.h + * @brief Error-checking library call wrappers + */ #ifndef SYSCALLS_H #define SYSCALLS_H diff --git a/lib/table.c b/lib/table.c index 7295532..a646d92 100644 --- a/lib/table.c +++ b/lib/table.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/table.c + * @brief Generic binary search + */ #include "common.h" #include "table.h" diff --git a/lib/table.h b/lib/table.h index 12c05c0..db237ac 100644 --- a/lib/table.h +++ b/lib/table.h @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/table.h + * @brief Generic binary search + */ #ifndef TABLE_H #define TABLE_H diff --git a/lib/timeval.h b/lib/timeval.h index 2911dd4..930ad24 100644 --- a/lib/timeval.h +++ b/lib/timeval.h @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/timeval.h + * @brief Arithmetic on timeval structures + */ #ifndef TIMEVAL_H #define TIMEVAL_H diff --git a/lib/trackdb-int.h b/lib/trackdb-int.h index cb00e14..6d5234e 100644 --- a/lib/trackdb-int.h +++ b/lib/trackdb-int.h @@ -15,7 +15,8 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/trackdb-int.h + * @brief Track database internals */ #ifndef TRACKDB_INT_H #define TRACKDB_INT_H diff --git a/lib/trackname.c b/lib/trackname.c index 36e438f..fa40c3b 100644 --- a/lib/trackname.c +++ b/lib/trackname.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/trackname.c + * @brief Track name calculation + */ #include "common.h" #include diff --git a/lib/trackname.h b/lib/trackname.h index 31c7df8..63b881b 100644 --- a/lib/trackname.h +++ b/lib/trackname.h @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/trackname.h + * @brief Track name calculation + */ #ifndef TRACKNAME_H #define TRACKNAME_H diff --git a/lib/trackorder.c b/lib/trackorder.c index df86e29..d0ae448 100644 --- a/lib/trackorder.c +++ b/lib/trackorder.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/trackorder.c + * @brief Track ordering + */ #include "common.h" #include diff --git a/lib/tracksort.c b/lib/tracksort.c index 5ae0d03..2f81739 100644 --- a/lib/tracksort.c +++ b/lib/tracksort.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file lib/tracksort.c + * @brief Track ordering + */ #include "common.h" #include "trackname.h" diff --git a/lib/unidata.c b/lib/unidata.c index db4334d..b22b5bc 100644 --- a/lib/unidata.c +++ b/lib/unidata.c @@ -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 diff --git a/lib/unidata.h b/lib/unidata.h index aa8814d..86f5fee 100644 --- a/lib/unidata.h +++ b/lib/unidata.h @@ -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 { diff --git a/lib/vacopy.h b/lib/vacopy.h index f933396..d152b36 100644 --- a/lib/vacopy.h +++ b/lib/vacopy.h @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/vacopy.h + * @brief va_copy fixup + */ #ifndef VACOPY_H #define VACOPY_H diff --git a/lib/vector.c b/lib/vector.c index 6803a14..4d798f1 100644 --- a/lib/vector.c +++ b/lib/vector.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/vector.c + * @brief Dynamic array utilities + */ #include "common.h" #include diff --git a/lib/version.c b/lib/version.c index e591222..e4eb005 100644 --- a/lib/version.c +++ b/lib/version.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file lib/version.c + * @brief Display version string and exit + */ #include "common.h" #include "syscalls.h" diff --git a/lib/version.h b/lib/version.h index 0b0a004..b8ee0d5 100644 --- a/lib/version.h +++ b/lib/version.h @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file lib/version.h + * @brief Display version string and exit + */ #ifndef VERSION_H #define VERSION_H diff --git a/lib/xgetdate.c b/lib/xgetdate.c index 9d8b492..d3a3862 100644 --- a/lib/xgetdate.c +++ b/lib/xgetdate.c @@ -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. diff --git a/plugins/exec.c b/plugins/exec.c index 6efc2bf..f6ed8b3 100644 --- a/plugins/exec.c +++ b/plugins/exec.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file plugins/exec.c + * @brief Plugin to play a track by executing a command + */ #include #include diff --git a/plugins/execraw.c b/plugins/execraw.c index c967fda..8af8c61 100644 --- a/plugins/execraw.c +++ b/plugins/execraw.c @@ -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" diff --git a/plugins/fs.c b/plugins/fs.c index 9e857f9..1099d14 100644 --- a/plugins/fs.c +++ b/plugins/fs.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file plugins/fs.c + * @brief Plugin to find tracks in a filesystem + */ #include #include diff --git a/plugins/mad.c b/plugins/mad.c index 1e40325..005c3e6 100644 --- a/plugins/mad.c +++ b/plugins/mad.c @@ -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. diff --git a/plugins/madshim.h b/plugins/madshim.h index 83a709b..5d73611 100644 --- a/plugins/madshim.h +++ b/plugins/madshim.h @@ -15,12 +15,13 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @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; diff --git a/plugins/notify.c b/plugins/notify.c index 8f9dc80..a0d7c11 100644 --- a/plugins/notify.c +++ b/plugins/notify.c @@ -15,6 +15,13 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @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" diff --git a/plugins/shell.c b/plugins/shell.c index 90cb4ac..bbd7a4e 100644 --- a/plugins/shell.c +++ b/plugins/shell.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file plugins/shell.c + * @brief Plugin to execute track players via the shell. + */ #include diff --git a/plugins/tracklength.c b/plugins/tracklength.c index 21b7fae..86a1fc8 100644 --- a/plugins/tracklength.c +++ b/plugins/tracklength.c @@ -15,6 +15,11 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file plugins/tracklength.c + * @brief Plugin to compute track lengths + * + * Currently implements MP3, OGG, FLAC and WAV. + */ #include diff --git a/scripts/make-unidata b/scripts/make-unidata index e0b7b6a..d1490cc 100755 --- a/scripts/make-unidata +++ b/scripts/make-unidata @@ -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"); diff --git a/server/api-server.c b/server/api-server.c index ce5e123..bfd8923 100644 --- a/server/api-server.c +++ b/server/api-server.c @@ -15,6 +15,11 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file server/api-server.c + * @brief Server API functions + * + * These functions are made available to server-side plugins. + */ #include "disorder-server.h" diff --git a/server/api.c b/server/api.c index e5783c1..fe9686c 100644 --- a/server/api.c +++ b/server/api.c @@ -15,7 +15,11 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @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 */ diff --git a/server/dbupgrade.c b/server/dbupgrade.c index e89cd4e..bd08eed 100644 --- a/server/dbupgrade.c +++ b/server/dbupgrade.c @@ -15,6 +15,11 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file server/dbupgrade.c + * @brief Database upgrade utility + * + * Invoked by the server when necessary. + */ #include "disorder-server.h" static DB_TXN *global_tid; diff --git a/server/deadlock.c b/server/deadlock.c index b53bbd5..3c13351 100644 --- a/server/deadlock.c +++ b/server/deadlock.c @@ -15,7 +15,11 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file server/deadlock.c + * @brief Deadlock monitor + * + * Spawned by the server. + */ #include "disorder-server.h" static const struct option options[] = { diff --git a/server/disorder-server.h b/server/disorder-server.h index c3a0e69..09eafbc 100644 --- a/server/disorder-server.h +++ b/server/disorder-server.h @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file server/disorder-server.h + * @brief Definitions for server and allied utilities + */ #ifndef DISORDER_SERVER_H #define DISORDER_SERVER_H diff --git a/server/disorderd.c b/server/disorderd.c index 10ff89b..e03fa42 100644 --- a/server/disorderd.c +++ b/server/disorderd.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file server/disorderd.c + * @brief Main DisOrder server + */ #include "disorder-server.h" static ev_source *ev; diff --git a/server/dump.c b/server/dump.c index af1d43d..e08b32f 100644 --- a/server/dump.c +++ b/server/dump.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file server/dump.c + * @brief Dump and restore database contents + */ #include "disorder-server.h" static const struct option options[] = { diff --git a/server/exports.c b/server/exports.c index 1a0bb7e..fb8426f 100644 --- a/server/exports.c +++ b/server/exports.c @@ -15,7 +15,12 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @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); diff --git a/server/play.c b/server/play.c index 2889e42..f657d6f 100644 --- a/server/play.c +++ b/server/play.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file server/play.c + * @brief Playing tracks + */ #include "disorder-server.h" #include diff --git a/server/plugin.c b/server/plugin.c index 2032d9d..6695d5a 100644 --- a/server/plugin.c +++ b/server/plugin.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file server/plugin.c + * @brief Server plugin interface + */ #include "disorder-server.h" #include diff --git a/server/queue-ops.c b/server/queue-ops.c index fd883aa..01987a2 100644 --- a/server/queue-ops.c +++ b/server/queue-ops.c @@ -15,6 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @file server/queue-ops.c + * @brief Track queues (server-specific code) + */ #include "disorder-server.h" static int find_in_list(struct queue_entry *needle, diff --git a/server/rescan.c b/server/rescan.c index f779d02..1380e24 100644 --- a/server/rescan.c +++ b/server/rescan.c @@ -15,7 +15,11 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file server/rescan.c + * @brief Rescanning utility + * + * Invoked by the server. + */ #include "disorder-server.h" static time_t last_report; diff --git a/server/state.c b/server/state.c index f23c06c..a99474e 100644 --- a/server/state.c +++ b/server/state.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file server/state.c + * @brief Global server state + */ #include "disorder-server.h" static const char *current_unix; diff --git a/server/stats.c b/server/stats.c index 772be13..81c92f4 100644 --- a/server/stats.c +++ b/server/stats.c @@ -15,6 +15,12 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ +/** @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" diff --git a/server/trackname.c b/server/trackname.c index 116fed5..ec84f68 100644 --- a/server/trackname.c +++ b/server/trackname.c @@ -15,7 +15,9 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ - +/** @file server/trackname.c + * @brief Utility to run the track name calculator in isolation + */ #include "disorder-server.h" static const struct option options[] = { diff --git a/tests/udplog.c b/tests/udplog.c index f8839c8..a27252c 100644 --- a/tests/udplog.c +++ b/tests/udplog.c @@ -17,7 +17,11 @@ * 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 -- [mdw]