* 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"
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
dcgi_expand("playing", 1);
}
-/*! disable
+/*$ disable
*
* Disables play.
*/
redirect(0);
}
-/*! enable
+/*$ enable
*
* Enables play.
*/
redirect(0);
}
-/*! random-disable
+/*$ random-disable
*
* Disables random play.
*/
redirect(0);
}
-/*! random-enable
+/*$ random-enable
*
* Enables random play.
*/
redirect(0);
}
-/*! pause
+/*$ pause
*
* Pauses the current track (if there is one and it's not paused already).
*/
redirect(0);
}
-/*! resume
+/*$ resume
*
* Resumes the current track (if there is one and it's paused).
*/
redirect(0);
}
-/*! remove
+/*$ remove
*
* Removes the track given by the \fBid\fR argument. If this is the currently
* playing track then it is scratched.
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
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.
return n;
}
-/*! volume
+/*$ volume
*
* If the \fBdelta\fR argument is set: adjust both channels by that amount (up
* if positive, down if negative).
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,
}
}
-/*! logout
+/*$ logout
*
* Logs out the current user and expands \fIlogin.tmpl\fR with \fBstatus\fR or
* \fB@error\fR set according to the result.
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
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
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
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
return 0;
}
-/*! prefs
+/*$ prefs
*
* Set preferences on a number of tracks.
*
* 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
*/
/** @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;
* 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.
* 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"
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.
return sink_writes(output, cgi_sgmlquote(v)) < 0 ? -1 : 0;
}
-/*! @version
+/*$ @version
*
* Expands to the local version string.
*/
cgi_sgmlquote(disorder_short_version_string)) < 0 ? -1 : 0;
}
-/*! @url
+/*$ @url
*
* Expands to the base URL of the web interface.
*/
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.
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.
return 0;
}
-/*! @user
+/*$ @user
*
* Expands to the logged-in username (which might be "guest"), or to
* the empty string if not connected.
return 0;
}
-/*! @part{TRACK|ID}{PART}{CONTEXT}
+/*$ @part{TRACK|ID}{PART}{CONTEXT}
*
* Expands to a track name part.
*
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.
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.
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.
return sink_writes(output, " ") < 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
return sink_writes(output, " ") < 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.
(dcgi_rights, disorder_user(dcgi_client), q));
}
-/*! @movable{ID}{DIR}
+/*$ @movable{ID}{DIR}
*
* Expands to "true" if track ID is movable and "false" otherwise.
*
q));
}
-/*! @playing{TEMPLATE}
+/*$ @playing{TEMPLATE}
*
* Expands to TEMPLATE, with the following expansions:
* - @id: the queue ID of the playing track
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
return 0;
}
-/*! @recent{TEMPLATE}
+/*$ @recent{TEMPLATE}
*
* For each track in the recently played list, expands TEMPLATE with the
* following expansions:
return 0;
}
-/*! @new{TEMPLATE}
+/*$ @new{TEMPLATE}
*
* For each track in the newly added list, expands TEMPLATE wit the following
* expansions:
return 0;
}
-/*! @volume{CHANNEL}
+/*$ @volume{CHANNEL}
*
* Expands to the volume in a given channel. CHANNEL must be "left" or
* "right".
? dcgi_volume_left : dcgi_volume_right) < 0 ? -1 : 0;
}
-/*! @isplaying
+/*$ @isplaying
*
* Expands to "true" if there is a playing track, otherwise "false".
*/
return mx_bool_result(output, !!dcgi_playing);
}
-/*! @isqueue
+/*$ @isqueue
*
* Expands to "true" if there the queue is nonempty, otherwise "false".
*/
return mx_bool_result(output, !!dcgi_queue);
}
-/*! @isrecent@
+/*$ @isrecent@
*
* Expands to "true" if there the recently played list is nonempty, otherwise
* "false".
return mx_bool_result(output, !!dcgi_recent);
}
-/*! @isnew
+/*$ @isnew
*
* Expands to "true" if there the newly added track list is nonempty, otherwise
* "false".
return mx_bool_result(output, !!dcgi_nnew);
}
-/*! @pref{TRACK}{KEY}
+/*$ @pref{TRACK}{KEY}
*
* Expands to a track preference.
*/
return 0;
}
-/*! @prefs{TRACK}{TEMPLATE}
+/*$ @prefs{TRACK}{TEMPLATE}
*
* For each track preference of track TRACK, expands TEMPLATE with the
* following expansions:
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
return sink_writes(output, cgi_sgmlquote(t)) < 0 ? -1 : 0;
}
-/*! @enabled@
+/*$ @enabled@
*
* Expands to "true" if playing is enabled, otherwise "false".
*/
return mx_bool_result(output, e);
}
-/*! @random-enabled
+/*$ @random-enabled
*
* Expands to "true" if random play is enabled, otherwise "false".
*/
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.
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
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.
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).
&& dcgi_playing->state == playing_paused));
}
-/*! @state{ID}@
+/*$ @state{ID}@
*
* Expands to the current state of track ID.
*/
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.
return 0;
}
-/*! @userinfo{PROPERTY}
+/*$ @userinfo{PROPERTY}
*
* Expands to the named property of the current user.
*/
return 0;
}
-/*! @error
+/*$ @error
*
* Expands to the latest error string.
*/
< 0 ? -1 : 0;
}
-/*! @status
+/*$ @status
*
* Expands to the latest status string.
*/
< 0 ? -1 : 0;
}
-/*! @image{NAME}
+/*$ @image{NAME}
*
* Expands to the URL of the image called NAME.
*
}
-/*! @tracks{DIR}{RE}{TEMPLATE}
+/*$ @tracks{DIR}{RE}{TEMPLATE}
*
* For each track below DIR, expands TEMPLATE with the
* following expansions:
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:
return disorder_search(c, terms, vecp, nvecp);
}
-/*! @search{KEYWORDS}{TEMPLATE}
+/*$ @search{KEYWORDS}{TEMPLATE}
*
* For each track matching KEYWORDS, expands TEMPLATE with the
* following expansions:
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.
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:
* 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
* 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"
}
/** @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
* @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,
* @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. */
}
/** @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,
* @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,
/** @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.
*/
/** @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,
}
/** @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
/** @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"
return path;
}
-/*! @include{TEMPLATE}@
+/*$ @include{TEMPLATE}@
*
* Includes TEMPLATE.
*
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
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.
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
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
return mx_bool_result(output, result);
}
-/*! @not{CONDITION}@
+/*$ @not{CONDITION}@
*
* Expands to "true" unless CONDITION is "true" in which case "false".
*/
return mx_bool_result(output, !mx_str2bool(args[0]));
}
-/*! @#{...}@
+/*$ @#{...}@
*
* Expands to nothing. The argument(s) are not fully evaluated, and no side
* effects occur.
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.
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).
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).
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
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,
return 0;
}
-/*! @basename{PATH}
+/*$ @basename{PATH}
*
* Expands to the UNQUOTED basename of PATH.
*/
return sink_writes(output, d_basename(args[0])) < 0 ? -1 : 0;
}
-/*! @dirname{PATH}
+/*$ @dirname{PATH}
*
* Expands to the UNQUOTED directory name of PATH.
*/
return sink_writes(output, d_dirname(args[0])) < 0 ? -1 : 0;
}
-/*! @q{STRING}
+/*$ @q{STRING}
*
* Expands to STRING.
*/
* @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),
* 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"
* 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
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];
* 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
}
/** @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
}
/** @brief Called with a new random track
+ * @param ev Event loop
* @param track Track name
*/
static void chosen_random_track(ev_source *ev,
/** @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
*
/******************************************************************************/
/** @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,
};
/** @brief Look up a scheduled event
+ * @param id Event ID
* @param actiondata Event description
* @return index in schedule_actions[] on success, -1 on error
*