chiark / gitweb /
Bring CGI docs pretty much up to date
[disorder] / server / macros-disorder.c
index a074573..2dc8098 100644 (file)
@@ -38,7 +38,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.
@@ -57,7 +57,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.
  */
@@ -69,7 +69,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.
  */
@@ -81,7 +81,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.
@@ -98,7 +98,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.
@@ -115,7 +115,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.
@@ -131,7 +131,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 +168,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 +180,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 +196,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 +233,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 +265,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 +285,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 +318,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 +346,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 +378,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 +411,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 +445,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 +460,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 +472,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 +484,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 +497,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 +510,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 +525,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 +564,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 +579,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 +594,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 +609,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 +635,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 +648,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 +664,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 +678,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 +693,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 +730,7 @@ static int exp_right(int nargs,
   return 0;
 }
 
-/* @userinfo{PROPERTY}
+/*! @userinfo{PROPERTY}
  *
  * Expands to the named property of the current user.
  */
@@ -747,7 +747,7 @@ static int exp_userinfo(int attribute((unused)) nargs,
   return 0;
 }
 
-/* @error
+/*! @error
  *
  * Expands to the latest error string.
  */
@@ -759,7 +759,7 @@ static int exp_error(int attribute((unused)) nargs,
               < 0 ? -1 : 0;
 }
 
-/* @status
+/*! @status
  *
  * Expands to the latest status string.
  */
@@ -771,7 +771,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.
  *
@@ -878,7 +878,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:
@@ -899,7 +899,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:
@@ -926,7 +926,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:
@@ -945,7 +945,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.
@@ -957,7 +957,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: