From: Richard Kettlewell <rjk@greenend.org.uk>
Date: Sat, 25 Oct 2008 16:30:40 +0000 (+0100)
Subject: Doxygen-clean
X-Git-Tag: 4.3~63
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/commitdiff_plain/59cf25c47fbda22f3f4e14399f0436cc6ed2c56f?hp=7751df38d656c9cf06fa8b545420303e69e72528

Doxygen-clean
---

diff --git a/cgi/actions.c b/cgi/actions.c
index 7634010..f63e519 100644
--- a/cgi/actions.c
+++ b/cgi/actions.c
@@ -15,13 +15,15 @@
  * 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/actions.c
+/** @file cgi/actions.c
  * @brief DisOrder web actions
  *
  * Actions are anything that the web interface does beyond passive template
  * expansion and inspection of state recieved from the server.  This means
  * playing tracks, editing prefs etc but also setting extra headers e.g. to
  * auto-refresh the playing list.
+ *
+ * See @ref lib/macros-builtin.c for docstring syntax.
  */
 
 #include "disorder-cgi.h"
@@ -45,14 +47,14 @@ static void redirect(const char *url) {
     fatal(errno, "error writing to stdout");
 }
 
-/*! playing
+/*$ playing
  *
  * Expands \fIplaying.tmpl\fR as if there was no special 'playing' action, but
  * adds a Refresh: field to the HTTP header.  The maximum refresh interval is
  * defined by \fBrefresh\fR (see \fBdisorder_config\fR(5)) but may be less if
  * the end of the track is near.
  */
-/*! manage
+/*$ manage
  *
  * Expands \fIplaying.tmpl\fR (NB not \fImanage.tmpl\fR) as if there was no
  * special 'playing' action, and adds a Refresh: field to the HTTP header.  The
@@ -103,7 +105,7 @@ static void act_playing(void) {
   dcgi_expand("playing", 1);
 }
 
-/*! disable
+/*$ disable
  *
  * Disables play.
  */
@@ -113,7 +115,7 @@ static void act_disable(void) {
   redirect(0);
 }
 
-/*! enable
+/*$ enable
  *
  * Enables play.
  */
@@ -123,7 +125,7 @@ static void act_enable(void) {
   redirect(0);
 }
 
-/*! random-disable
+/*$ random-disable
  *
  * Disables random play.
  */
@@ -133,7 +135,7 @@ static void act_random_disable(void) {
   redirect(0);
 }
 
-/*! random-enable
+/*$ random-enable
  *
  * Enables random play.
  */
@@ -143,7 +145,7 @@ static void act_random_enable(void) {
   redirect(0);
 }
 
-/*! pause
+/*$ pause
  *
  * Pauses the current track (if there is one and it's not paused already).
  */
@@ -153,7 +155,7 @@ static void act_pause(void) {
   redirect(0);
 }
 
-/*! resume
+/*$ resume
  *
  * Resumes the current track (if there is one and it's paused).
  */
@@ -163,7 +165,7 @@ static void act_resume(void) {
   redirect(0);
 }
 
-/*! remove
+/*$ remove
  *
  * Removes the track given by the \fBid\fR argument.  If this is the currently
  * playing track then it is scratched.
@@ -199,7 +201,7 @@ static void act_remove(void) {
   redirect(0);
 }
 
-/*! move
+/*$ move
  *
  * Moves the track given by the \fBid\fR argument the distance given by the
  * \fBdelta\fR argument.  If this is positive the track is moved earlier in the
@@ -229,7 +231,7 @@ static void act_move(void) {
   redirect(0);
 }
 
-/*! play
+/*$ play
  *
  * Play the track given by the \fBtrack\fR argument, or if that is not set all
  * the tracks in the directory given by the \fBdir\fR argument.
@@ -262,7 +264,7 @@ static int clamp(int n, int min, int max) {
   return n;
 }
 
-/*! volume
+/*$ volume
  *
  * If the \fBdelta\fR argument is set: adjust both channels by that amount (up
  * if positive, down if negative).
@@ -324,7 +326,7 @@ static int login_as(const char *username, const char *password) {
   return 0;                             /* OK */
 }
 
-/*! login
+/*$ login
  *
  * If \fBusername\fR and \fBpassword\fR are set (and the username isn't
  * "guest") then attempt to log in using those credentials.  On success,
@@ -359,7 +361,7 @@ static void act_login(void) {
   }
 }
 
-/*! logout
+/*$ logout
  *
  * Logs out the current user and expands \fIlogin.tmpl\fR with \fBstatus\fR or
  * \fB@error\fR set according to the result.
@@ -384,7 +386,7 @@ static void act_logout(void) {
   dcgi_expand("login", 1);
 }
 
-/*! register
+/*$ register
  *
  * Register a new user using \fBusername\fR, \fBpassword1\fR, \fBpassword2\fR
  * and \fBemail\fR and expands \fIlogin.tmpl\fR with \fBstatus\fR or
@@ -451,7 +453,7 @@ static void act_register(void) {
   dcgi_expand("login", 1);
 }
 
-/*! confirm
+/*$ confirm
  *
  * Confirm a user registration using the nonce supplied in \fBc\fR and expands
  * \fIlogin.tmpl\fR with \fBstatus\fR or \fB@error\fR set according to the
@@ -487,7 +489,7 @@ static void act_confirm(void) {
   dcgi_expand("login", 1);
 }
 
-/*! edituser
+/*$ edituser
  *
  * Edit user details using \fBusername\fR, \fBchangepassword1\fR,
  * \fBchangepassword2\fR and \fBemail\fR and expands \fIlogin.tmpl\fR with
@@ -548,7 +550,7 @@ static void act_edituser(void) {
   dcgi_expand("login", 1);
 }
 
-/*! reminder
+/*$ reminder
  *
  * Issue an email password reminder to \fBusername\fR and expands
  * \fIlogin.tmpl\fR with \fBstatus\fR or \fB@error\fR set according to the
@@ -630,7 +632,7 @@ static int process_prefs(int numfile) {
   return 0;
 }
 
-/*! prefs
+/*$ prefs
  *
  * Set preferences on a number of tracks.
  *
diff --git a/cgi/cgimain.c b/cgi/cgimain.c
index 884a0a0..583af30 100644
--- a/cgi/cgimain.c
+++ b/cgi/cgimain.c
@@ -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 server/cgimain.c
+/** @file cgi/cgimain.c
  * @brief DisOrder CGI
  */
 
diff --git a/cgi/login.c b/cgi/login.c
index 3570f9a..d490151 100644
--- a/cgi/login.c
+++ b/cgi/login.c
@@ -55,7 +55,7 @@ static int better_cookie(const struct cookie *a, const struct cookie *b) {
 /** @brief Login cookie */
 char *dcgi_cookie;
 
-/** @brief Set @ref login_cookie */
+/** @brief Set @ref dcgi_cookie */
 void dcgi_get_cookie(void) {
   const char *cookie_env;
   int n, best_cookie;
diff --git a/cgi/lookup.c b/cgi/lookup.c
index 7b9a372..fd94900 100644
--- a/cgi/lookup.c
+++ b/cgi/lookup.c
@@ -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 server/lookup.c
+/** @file cgi/lookup.c
  * @brief Server lookups
  *
  * To improve performance many server lookups are cached.
diff --git a/cgi/macros-disorder.c b/cgi/macros-disorder.c
index cd00f50..6348f47 100644
--- a/cgi/macros-disorder.c
+++ b/cgi/macros-disorder.c
@@ -15,8 +15,10 @@
  * 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/macros-disorder.c
+/** @file cgi/macros-disorder.c
  * @brief DisOrder-specific expansions
+ *
+ * See @ref lib/macros-builtin.c for docstring syntax.
  */
 
 #include "disorder-cgi.h"
@@ -35,7 +37,7 @@ static const char *make_index(int i) {
   return s;
 }
 
-/*! @server-version
+/*$ @server-version
  *
  * Expands to the server's version string, or a (safe to use) error
  * value if the server is unavailable or broken.
@@ -54,7 +56,7 @@ static int exp_server_version(int attribute((unused)) nargs,
   return sink_writes(output, cgi_sgmlquote(v)) < 0 ? -1 : 0;
 }
 
-/*! @version
+/*$ @version
  *
  * Expands to the local version string.
  */
@@ -66,7 +68,7 @@ static int exp_version(int attribute((unused)) nargs,
                      cgi_sgmlquote(disorder_short_version_string)) < 0 ? -1 : 0;
 }
 
-/*! @url
+/*$ @url
  *
  * Expands to the base URL of the web interface.
  */
@@ -78,7 +80,7 @@ static int exp_url(int attribute((unused)) nargs,
                      cgi_sgmlquote(config->url)) < 0 ? -1 : 0;
 }
 
-/*! @arg{NAME}
+/*$ @arg{NAME}
  *
  * Expands to the UNQUOTED form of CGI argument NAME, or the empty string if
  * there is no such argument.  Use @argq for a quick way to quote the argument.
@@ -95,7 +97,7 @@ static int exp_arg(int attribute((unused)) nargs,
     return 0;
 }
 
-/*! @argq{NAME}
+/*$ @argq{NAME}
  *
  * Expands to the (quoted) form of CGI argument NAME, or the empty string if
  * there is no such argument.  Use @arg for the unquoted argument.
@@ -112,7 +114,7 @@ static int exp_argq(int attribute((unused)) nargs,
     return 0;
 }
 
-/*! @user
+/*$ @user
  *
  * Expands to the logged-in username (which might be "guest"), or to
  * the empty string if not connected.
@@ -128,7 +130,7 @@ static int exp_user(int attribute((unused)) nargs,
   return 0;
 }
 
-/*! @part{TRACK|ID}{PART}{CONTEXT}
+/*$ @part{TRACK|ID}{PART}{CONTEXT}
  *
  * Expands to a track name part.
  *
@@ -168,7 +170,7 @@ static int exp_part(int nargs,
   return 0;
 }
 
-/*! @quote{STRING}
+/*$ @quote{STRING}
  *
  * SGML-quotes STRING.  Note that most expansion results are already suitable
  * quoted, so this expansion is usually not required.
@@ -180,7 +182,7 @@ static int exp_quote(int attribute((unused)) nargs,
   return sink_writes(output, cgi_sgmlquote(args[0])) < 0 ? -1 : 0;
 }
 
-/*! @who{ID}
+/*$ @who{ID}
  *
  * Expands to the name of the submitter of track ID, which must be a playing
  * track, in the queue, or in the recent list.
@@ -196,7 +198,7 @@ static int exp_who(int attribute((unused)) nargs,
   return 0;
 }
 
-/*! @when{ID}
+/*$ @when{ID}
  *
  * Expands to the time a track started or is expected to start.  The track must
  * be a playing track, in the queue, or in the recent list.
@@ -233,7 +235,7 @@ static int exp_when(int attribute((unused)) nargs,
   return sink_writes(output, "&nbsp;") < 0 ? -1 : 0;
 }
 
-/*! @length{ID|TRACK}
+/*$ @length{ID|TRACK}
  *
  * Expands to the length of a track, identified by its queue ID or its name.
  * If it is the playing track (identified by ID) then the amount played so far
@@ -265,7 +267,7 @@ static int exp_length(int attribute((unused)) nargs,
   return sink_writes(output, "&nbsp;") < 0 ? -1 : 0;
 }
 
-/*! @removable{ID}
+/*$ @removable{ID}
  *
  * Expands to "true" if track ID is removable (or scratchable, if it is the
  * playing track) and "false" otherwise.
@@ -285,7 +287,7 @@ static int exp_removable(int attribute((unused)) nargs,
                             (dcgi_rights, disorder_user(dcgi_client), q));
 }
 
-/*! @movable{ID}{DIR}
+/*$ @movable{ID}{DIR}
  *
  * Expands to "true" if track ID is movable and "false" otherwise.
  *
@@ -318,7 +320,7 @@ static int exp_movable(int  nargs,
                                       q));
 }
 
-/*! @playing{TEMPLATE}
+/*$ @playing{TEMPLATE}
  *
  * Expands to TEMPLATE, with the following expansions:
  * - @id: the queue ID of the playing track
@@ -346,7 +348,7 @@ static int exp_playing(int nargs,
                    output, u);
 }
 
-/*! @queue{TEMPLATE}
+/*$ @queue{TEMPLATE}
  *
  * For each track in the queue, expands TEMPLATE with the following expansions:
  * - @id: the queue ID of the track
@@ -378,7 +380,7 @@ static int exp_queue(int attribute((unused)) nargs,
   return 0;
 }
 
-/*! @recent{TEMPLATE}
+/*$ @recent{TEMPLATE}
  *
  * For each track in the recently played list, expands TEMPLATE with the
  * following expansions:
@@ -411,7 +413,7 @@ static int exp_recent(int attribute((unused)) nargs,
   return 0;
 }
 
-/*! @new{TEMPLATE}
+/*$ @new{TEMPLATE}
  *
  * For each track in the newly added list, expands TEMPLATE wit the following
  * expansions:
@@ -445,7 +447,7 @@ static int exp_new(int attribute((unused)) nargs,
   return 0;
 }
 
-/*! @volume{CHANNEL}
+/*$ @volume{CHANNEL}
  *
  * Expands to the volume in a given channel.  CHANNEL must be "left" or
  * "right".
@@ -460,7 +462,7 @@ static int exp_volume(int attribute((unused)) nargs,
                          ? dcgi_volume_left : dcgi_volume_right) < 0 ? -1 : 0;
 }
 
-/*! @isplaying
+/*$ @isplaying
  *
  * Expands to "true" if there is a playing track, otherwise "false".
  */
@@ -472,7 +474,7 @@ static int exp_isplaying(int attribute((unused)) nargs,
   return mx_bool_result(output, !!dcgi_playing);
 }
 
-/*! @isqueue
+/*$ @isqueue
  *
  * Expands to "true" if there the queue is nonempty, otherwise "false".
  */
@@ -484,7 +486,7 @@ static int exp_isqueue(int attribute((unused)) nargs,
   return mx_bool_result(output, !!dcgi_queue);
 }
 
-/*! @isrecent@
+/*$ @isrecent@
  *
  * Expands to "true" if there the recently played list is nonempty, otherwise
  * "false".
@@ -497,7 +499,7 @@ static int exp_isrecent(int attribute((unused)) nargs,
   return mx_bool_result(output, !!dcgi_recent);
 }
 
-/*! @isnew
+/*$ @isnew
  *
  * Expands to "true" if there the newly added track list is nonempty, otherwise
  * "false".
@@ -510,7 +512,7 @@ static int exp_isnew(int attribute((unused)) nargs,
   return mx_bool_result(output, !!dcgi_nnew);
 }
 
-/*! @pref{TRACK}{KEY}
+/*$ @pref{TRACK}{KEY}
  *
  * Expands to a track preference.
  */
@@ -525,7 +527,7 @@ static int exp_pref(int attribute((unused)) nargs,
   return 0;
 }
 
-/*! @prefs{TRACK}{TEMPLATE}
+/*$ @prefs{TRACK}{TEMPLATE}
  *
  * For each track preference of track TRACK, expands TEMPLATE with the
  * following expansions:
@@ -564,7 +566,7 @@ static int exp_prefs(int attribute((unused)) nargs,
   return 0;
 }
 
-/*! @transform{TRACK}{TYPE}{CONTEXT}
+/*$ @transform{TRACK}{TYPE}{CONTEXT}
  *
  * Transforms a track name (if TYPE is "track") or directory name (if type is
  * "dir").  CONTEXT should be the context, if it is left out then "display" is
@@ -579,7 +581,7 @@ static int exp_transform(int nargs,
   return sink_writes(output, cgi_sgmlquote(t)) < 0 ? -1 : 0;
 }
 
-/*! @enabled@
+/*$ @enabled@
  *
  * Expands to "true" if playing is enabled, otherwise "false".
  */
@@ -594,7 +596,7 @@ static int exp_enabled(int attribute((unused)) nargs,
   return mx_bool_result(output, e);
 }
 
-/*! @random-enabled
+/*$ @random-enabled
  *
  * Expands to "true" if random play is enabled, otherwise "false".
  */
@@ -609,7 +611,7 @@ static int exp_random_enabled(int attribute((unused)) nargs,
   return mx_bool_result(output, e);
 }
 
-/*! @trackstate{TRACK}
+/*$ @trackstate{TRACK}
  *
  * Expands to "playing" if TRACK is currently playing, or "queue" if it is in
  * the queue, otherwise to nothing.
@@ -635,7 +637,7 @@ static int exp_trackstate(int attribute((unused)) nargs,
   return 0;
 }
 
-/*! @thisurl
+/*$ @thisurl
  *
  * Expands to an UNQUOTED URL which points back to the current page.  (NB it
  * might not be byte for byte identical - for instance, CGI arguments might be
@@ -648,7 +650,7 @@ static int exp_thisurl(int attribute((unused)) nargs,
   return sink_writes(output, cgi_thisurl(config->url)) < 0 ? -1 : 0;
 }
 
-/*! @resolve{TRACK}
+/*$ @resolve{TRACK}
  *
  * Expands to an UNQUOTED name for the TRACK that is not an alias, or to
  * nothing if it is not a valid track.
@@ -664,7 +666,7 @@ static int exp_resolve(int attribute((unused)) nargs,
   return 0;
 }
 
-/*! @paused
+/*$ @paused
  *
  * Expands to "true" if the playing track is paused, to "false" if it is
  * playing (or if there is no playing track at all).
@@ -678,7 +680,7 @@ static int exp_paused(int attribute((unused)) nargs,
                                  && dcgi_playing->state == playing_paused));
 }
 
-/*! @state{ID}@
+/*$ @state{ID}@
  *
  * Expands to the current state of track ID.
  */
@@ -693,7 +695,7 @@ static int exp_state(int attribute((unused)) nargs,
   return 0;
 }
 
-/*! @right{RIGHT}{WITH-RIGHT}{WITHOUT-RIGHT}@
+/*$ @right{RIGHT}{WITH-RIGHT}{WITHOUT-RIGHT}@
  *
  * Expands to WITH-RIGHT if the current user has right RIGHT, otherwise to
  * WITHOUT-RIGHT.  The WITHOUT-RIGHT argument may be left out.
@@ -730,7 +732,7 @@ static int exp_right(int nargs,
   return 0;
 }
 
-/*! @userinfo{PROPERTY}
+/*$ @userinfo{PROPERTY}
  *
  * Expands to the named property of the current user.
  */
@@ -747,7 +749,7 @@ static int exp_userinfo(int attribute((unused)) nargs,
   return 0;
 }
 
-/*! @error
+/*$ @error
  *
  * Expands to the latest error string.
  */
@@ -759,7 +761,7 @@ static int exp_error(int attribute((unused)) nargs,
               < 0 ? -1 : 0;
 }
 
-/*! @status
+/*$ @status
  *
  * Expands to the latest status string.
  */
@@ -771,7 +773,7 @@ static int exp_status(int attribute((unused)) nargs,
               < 0 ? -1 : 0;
 }
 
-/*! @image{NAME}
+/*$ @image{NAME}
  *
  * Expands to the URL of the image called NAME.
  *
@@ -862,7 +864,7 @@ static int exp__files_dirs(int nargs,
 
 }
 
-/*! @tracks{DIR}{RE}{TEMPLATE}
+/*$ @tracks{DIR}{RE}{TEMPLATE}
  *
  * For each track below DIR, expands TEMPLATE with the
  * following expansions:
@@ -883,7 +885,7 @@ static int exp_tracks(int nargs,
   return exp__files_dirs(nargs, args, output, u, "track", disorder_files);
 }
 
-/*! @dirs{DIR}{RE}{TEMPLATE}
+/*$ @dirs{DIR}{RE}{TEMPLATE}
  *
  * For each directory below DIR, expands TEMPLATE with the
  * following expansions:
@@ -910,7 +912,7 @@ static int exp__search_shim(disorder_client *c, const char *terms,
   return disorder_search(c, terms, vecp, nvecp);
 }
 
-/*! @search{KEYWORDS}{TEMPLATE}
+/*$ @search{KEYWORDS}{TEMPLATE}
  *
  * For each track matching KEYWORDS, expands TEMPLATE with the
  * following expansions:
@@ -929,7 +931,7 @@ static int exp_search(int nargs,
   return exp__files_dirs(nargs, args, output, u, "track", exp__search_shim);
 }
 
-/*! @label{NAME}
+/*$ @label{NAME}
  *
  * Expands to label NAME from options.labels.  Undefined lables expand to the
  * last dot-separated component, e.g. X.Y.Z to Z.
@@ -941,7 +943,7 @@ static int exp_label(int attribute((unused)) nargs,
   return sink_writes(output, option_label(args[0])) < 0 ? -1 : 0;
 }
 
-/*! @breadcrumbs{DIR}{TEMPLATE}
+/*$ @breadcrumbs{DIR}{TEMPLATE}
  *
  * Expands TEMPLATE for each directory in the path up to DIR, excluding the root
  * but including DIR itself, with the following expansions:
diff --git a/cgi/options.c b/cgi/options.c
index b56b424..05712c2 100644
--- a/cgi/options.c
+++ b/cgi/options.c
@@ -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 server/options.c
+/** @file cgi/options.c
  * @brief CGI options
  *
  * Options represent an additional configuration system private to the
diff --git a/disobedience/choose-search.c b/disobedience/choose-search.c
index e27640c..b06e9f9 100644
--- a/disobedience/choose-search.c
+++ b/disobedience/choose-search.c
@@ -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 disobedience/search.c
+/** @file disobedience/choose-search.c
  * @brief Search support
  */
 #include "disobedience.h"
diff --git a/disobedience/choose.c b/disobedience/choose.c
index beebe46..d1e9515 100644
--- a/disobedience/choose.c
+++ b/disobedience/choose.c
@@ -103,7 +103,7 @@ int choose_can_autocollapse(GtkTreeIter *iter) {
 }
 
 /** @brief Remove node @p it and all its children
- * @param Iterator, updated to point to next
+ * @param it Iterator, updated to point to next
  * @return True if iterator remains valid
  *
  * TODO is this necessary?  gtk_tree_store_remove() does not document what
@@ -163,12 +163,12 @@ static void choose_set_state(const char attribute((unused)) *event,
  * @param parent_ref Node to populate or NULL to fill root
  * @param nvec Number of children to add
  * @param vec Children
- * @param files 1 if children are files, 0 if directories
+ * @param isfile 1 if children are files, 0 if directories
  *
  * Adjusts the set of files (or directories) below @p parent_ref to match those
  * listed in @p nvec and @p vec.
  *
- * @parent_ref will be destroyed.
+ * @p parent_ref will be destroyed.
  */
 static void choose_populate(GtkTreeRowReference *parent_ref,
                             int nvec, char **vec,
diff --git a/disobedience/lookup.c b/disobedience/lookup.c
index 8255cfd..f160501 100644
--- a/disobedience/lookup.c
+++ b/disobedience/lookup.c
@@ -79,7 +79,6 @@ static void namepart_fill(const char *track,
  * @param track Track name
  * @param context Context
  * @param part Name part
- * @param lookup If nonzero, will schedule a lookup for unknown values
  *
  * If it is in the cache then just return its value.  If not then look it up
  * and arrange for the queues to be updated when its value is available. */
diff --git a/disobedience/popup.c b/disobedience/popup.c
index adc3224..6504722 100644
--- a/disobedience/popup.c
+++ b/disobedience/popup.c
@@ -55,7 +55,7 @@ void popup(GtkWidget **menup,
 }
 
 /** @brief Make sure the right thing is selected
- * @param widget Tree view
+ * @param treeview Tree view
  * @param event Mouse event
  */
 void ensure_selected(GtkTreeView *treeview,
diff --git a/disobedience/users.c b/disobedience/users.c
index 3a17eb0..1d2a169 100644
--- a/disobedience/users.c
+++ b/disobedience/users.c
@@ -348,6 +348,8 @@ static void users_details_destroyed(GtkWidget attribute((unused)) *widget,
  * @param email Email address
  * @param rights User rights string
  * @param password Password
+ * @param nameflags Visibility/editability for username
+ * @param flags Visibility/editability for other fields
  */
 static void users_makedetails(const char *name,
                               const char *email,
diff --git a/lib/eclient.h b/lib/eclient.h
index 57d202a..6578a75 100644
--- a/lib/eclient.h
+++ b/lib/eclient.h
@@ -125,7 +125,7 @@ typedef struct disorder_eclient_log_callbacks {
   /** @brief Called when @p id is removed from the recent list */
   void (*recent_removed)(void *v, const char *id);
 
-  /** @brief Called when @id is removed from the queue
+  /** @brief Called when @p id is removed from the queue
    *
    * @p user might be 0.
    */
diff --git a/lib/filepart.c b/lib/filepart.c
index 7e6f30c..20889af 100644
--- a/lib/filepart.c
+++ b/lib/filepart.c
@@ -26,8 +26,8 @@
 
 /** @brief Parse a filename
  * @param path Filename to parse
- * @param Where to put directory name, or NULL
- * @param Where to put basename, or NULL
+ * @param dirnamep Where to put directory name, or NULL
+ * @param basenamep Where to put basename, or NULL
  */
 static void parse_filename(const char *path,
                            char **dirnamep,
@@ -102,7 +102,7 @@ char *d_dirname(const char *path) {
 }
 
 /** @brief Return the basename part of @p path
- * @param Path to parse
+ * @param path Path to parse
  * @return Base part of @p path
  *
  * Extracts the base part of @p path.  This is a simple lexical transformation
diff --git a/lib/macros-builtin.c b/lib/macros-builtin.c
index ef98c8f..8c88f72 100644
--- a/lib/macros-builtin.c
+++ b/lib/macros-builtin.c
@@ -19,8 +19,16 @@
 /** @file lib/macros-builtin.c
  * @brief Built-in expansions
  *
- * This is a grab-bag of non-domain-specific expansions.  Documentation will be
- * generated from the comments at the head of each function.
+ * This is a grab-bag of non-domain-specific expansions
+ *
+ * Documentation is generated from the comments at the head of each function.
+ * The comment should have a '$' and the expansion name on the first line and
+ * should have a blank line between each paragraph.
+ *
+ * To make a bulleted list, put a '-' at the start of each line.
+ *
+ * You can currently get away with troff markup but this is horribly ugly and
+ * might be changed.
  */
 
 #include "common.h"
@@ -91,7 +99,7 @@ char *mx_find(const char *name, int report) {
   return path;
 }
 
-/*! @include{TEMPLATE}@
+/*$ @include{TEMPLATE}@
  *
  * Includes TEMPLATE.
  *
@@ -146,7 +154,7 @@ static int exp_include(int attribute((unused)) nargs,
   return 0;
 }
 
-/*! @include{COMMAND}@
+/*$ @include{COMMAND}@
  *
  * Executes COMMAND via the shell (using "sh -c") and copies its
  * standard output to the template output.  The shell command output
@@ -195,7 +203,7 @@ static int exp_shell(int attribute((unused)) nargs,
   return 0;
 }
 
-/*! @if{CONDITION}{IF-TRUE}{IF-FALSE}@
+/*$ @if{CONDITION}{IF-TRUE}{IF-FALSE}@
  *
  * If CONDITION is "true" then evaluates to IF-TRUE.  Otherwise
  * evaluates to IF-FALSE.  The IF-FALSE part is optional.
@@ -217,7 +225,7 @@ static int exp_if(int nargs,
     return 0;
 }
 
-/*! @and{BRANCH}{BRANCH}...@
+/*$ @and{BRANCH}{BRANCH}...@
  *
  * Expands to "true" if all the branches are "true" otherwise to "false".  If
  * there are no brances then the result is "true".  Only as many branches as
@@ -243,7 +251,7 @@ static int exp_and(int nargs,
   return mx_bool_result(output, result);
 }
 
-/*! @or{BRANCH}{BRANCH}...@
+/*$ @or{BRANCH}{BRANCH}...@
  *
  * Expands to "true" if any of the branches are "true" otherwise to "false".
  * If there are no brances then the result is "false".  Only as many branches
@@ -269,7 +277,7 @@ static int exp_or(int nargs,
   return mx_bool_result(output, result);
 }
 
-/*! @not{CONDITION}@
+/*$ @not{CONDITION}@
  *
  * Expands to "true" unless CONDITION is "true" in which case "false".
  */
@@ -280,7 +288,7 @@ static int exp_not(int attribute((unused)) nargs,
   return mx_bool_result(output, !mx_str2bool(args[0]));
 }
 
-/*! @#{...}@
+/*$ @#{...}@
  *
  * Expands to nothing.  The argument(s) are not fully evaluated, and no side
  * effects occur.
@@ -292,7 +300,7 @@ static int exp_comment(int attribute((unused)) nargs,
   return 0;
 }
 
-/*! @urlquote{STRING}@
+/*$ @urlquote{STRING}@
  *
  * URL-quotes a string, i.e. replaces any characters not safe to use unquoted
  * in a URL with %-encoded form.
@@ -307,7 +315,7 @@ static int exp_urlquote(int attribute((unused)) nargs,
     return 0;
 }
 
-/*! @eq{S1}{S2}...@
+/*$ @eq{S1}{S2}...@
  *
  * Expands to "true" if all the arguments are identical, otherwise to "false"
  * (i.e. if any pair of arguments differs).
@@ -331,7 +339,7 @@ static int exp_eq(int nargs,
   return mx_bool_result(output, result);
 }
 
-/*! @ne{S1}{S2}...@
+/*$ @ne{S1}{S2}...@
  *
  * Expands to "true" if all of the arguments differ from one another, otherwise
  * to "false" (i.e. if any value appears more than once).
@@ -355,7 +363,7 @@ static int exp_ne(int nargs,
   return mx_bool_result(output, result);
 }
 
-/*! @discard{...}@
+/*$ @discard{...}@
  *
  * Expands to nothing.  Unlike the comment expansion @#{...}, side effects of
  * arguments are not suppressed.  So this can be used to surround a collection
@@ -368,7 +376,7 @@ static int exp_discard(int attribute((unused)) nargs,
   return 0;
 }
 
-/*! @define{NAME}{ARG1 ARG2...}{DEFINITION}@
+/*$ @define{NAME}{ARG1 ARG2...}{DEFINITION}@
  *
  * Define a macro.  The macro will be called NAME and will act like an
  * expansion.  When it is expanded, the expansion is replaced by DEFINITION,
@@ -391,7 +399,7 @@ static int exp_define(int attribute((unused)) nargs,
   return 0;
 }
 
-/*! @basename{PATH}
+/*$ @basename{PATH}
  *
  * Expands to the UNQUOTED basename of PATH.
  */
@@ -402,7 +410,7 @@ static int exp_basename(int attribute((unused)) nargs,
   return sink_writes(output, d_basename(args[0])) < 0 ? -1 : 0;
 }
 
-/*! @dirname{PATH}
+/*$ @dirname{PATH}
  *
  * Expands to the UNQUOTED directory name of PATH.
  */
@@ -413,7 +421,7 @@ static int exp_dirname(int attribute((unused)) nargs,
   return sink_writes(output, d_dirname(args[0])) < 0 ? -1 : 0;
 }
 
-/*! @q{STRING}
+/*$ @q{STRING}
  *
  * Expands to STRING.
  */
diff --git a/lib/trackdb.c b/lib/trackdb.c
index 42ba36e..8769cca 100644
--- a/lib/trackdb.c
+++ b/lib/trackdb.c
@@ -2246,7 +2246,7 @@ static int reap_rescan(ev_source attribute((unused)) *ev,
  * @param ev Event loop or 0 to block
  * @param recheck 1 to recheck lengths, 0 to suppress check
  * @param rescanned Called on completion (if not NULL)
- * @param u Passed to @p rescanned
+ * @param ru Passed to @p rescanned
  */
 void trackdb_rescan(ev_source *ev, int recheck,
                     void (*rescanned)(void *ru),
diff --git a/libtests/test.c b/libtests/test.c
index 65a3ab0..6b2435e 100644
--- a/libtests/test.c
+++ b/libtests/test.c
@@ -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/test.c @brief Library tests */
+/** @file libtests/test.c @brief Library tests */
 
 #include "test.h"
 #include "version.h"
diff --git a/libtests/test.h b/libtests/test.h
index a03b5d1..b940413 100644
--- a/libtests/test.h
+++ b/libtests/test.h
@@ -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/test.h @brief Library tests */
+/** @file libtests/test.h @brief Library tests */
 
 #ifndef TEST_H
 #define TEST_H
diff --git a/scripts/macro-docs b/scripts/macro-docs
index 51586ea..265ee35 100755
--- a/scripts/macro-docs
+++ b/scripts/macro-docs
@@ -6,7 +6,7 @@ my $name;
 my $docs;
 while(defined($_ = <>)) {
   chomp;
-  if(!defined $name and m,^/\*! (\@?([a-z\-]+).*),) {
+  if(!defined $name and m,^/\*\$ (\@?([a-z\-]+).*),) {
     $name = $2;
     my $heading = $1;
     $docs = [$heading];
diff --git a/server/choose.c b/server/choose.c
index a4bf443..e620a8d 100644
--- a/server/choose.c
+++ b/server/choose.c
@@ -16,7 +16,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 choose.c
+/** @file server/choose.c
  * @brief Random track chooser
  *
  * Picks a track at random and writes it to standard output.  If for
diff --git a/server/disorderd.c b/server/disorderd.c
index 838c993..10ff89b 100644
--- a/server/disorderd.c
+++ b/server/disorderd.c
@@ -96,7 +96,7 @@ static int periodic_callback(ev_source *ev_,
 }
 
 /** @brief Create a periodic action
- * @param ev Event loop
+ * @param ev_ Event loop
  * @param callback Callback function
  * @param period Interval between calls in seconds
  * @param immediate If true, call @p callback straight away
diff --git a/server/play.c b/server/play.c
index b6b6298..2889e42 100644
--- a/server/play.c
+++ b/server/play.c
@@ -478,6 +478,7 @@ void abandon(ev_source attribute((unused)) *ev,
 }
 
 /** @brief Called with a new random track
+ * @param ev Event loop
  * @param track Track name
  */
 static void chosen_random_track(ev_source *ev,
diff --git a/server/schedule.c b/server/schedule.c
index 2e5887d..088229e 100644
--- a/server/schedule.c
+++ b/server/schedule.c
@@ -95,6 +95,9 @@ static const char *const schedule_required[] = {"when", "who", "action"};
 
 /** @brief Parse a scheduled event key and data
  * @param k Pointer to key
+ * @param d Pointer to data
+ * @param idp Where to store event ID
+ * @param actiondatap Where to store parsed data
  * @param whenp Where to store timestamp
  * @return 0 on success, non-0 on error
  *
@@ -225,8 +228,9 @@ void schedule_init(ev_source *ev) {
 /******************************************************************************/
 
 /** @brief Create a scheduled event
- * @param ev Event loop
+ * @param id Event ID
  * @param actiondata Action data
+ * @param tid Containing transaction
  */
 static int schedule_add_tid(const char *id,
 			    struct kvp *actiondata,
@@ -416,6 +420,7 @@ static struct {
 };
 
 /** @brief Look up a scheduled event
+ * @param id Event ID
  * @param actiondata Event description
  * @return index in schedule_actions[] on success, -1 on error
  *