gui

diff --git a/error.h b/error.h
index 971d3e7f9b7df5a1c96744cc003f93343cd0d6c9..7f540555d9392f91d6da3ccc67e271e5697f861b 100644 (file)
--- a/error.h
+++ b/error.h
@@ -2,7 +2,6 @@
 
 /** \file error.h List of error codes and messages. */
 
-/** \cond para_error */
 /** Codes and messages. */
 #define PARA_ERRORS \
        PARA_ERROR(SUCCESS, "success"), \

diff --git a/gui.c b/gui.c
index 81385301255fccd7135ae9a5551d5d68c3bfd885..bb323084888d8ea8a50f59c2928c6115041ab927 100644 (file)
--- a/gui.c
+++ b/gui.c
@@ -1,6 +1,25 @@
 /* Copyright (C) 1998 Andre Noll <maan@tuebingen.mpg.de>, see file COPYING. */
 
-/** \file gui.c Curses-based interface for paraslash. */
+/** \file gui.c Curses-based user interface.
+ *
+ * This file contains the bulk of the source code of para_gui(1), including
+ * main(). Another related source file is \ref gui_theme.c, which contains
+ * the theme definitions.
+ *
+ * para_gui(1) employs the scheduler to perform I/O on various file descriptors
+ * without threading. It does not use the buffer tree API, though.
+ *
+ * At startup the stat subcommand of para_audioc(1) is executed to obtain
+ * status information about para_server(1) and para_audiod(1). Moreover,
+ * the program runs arbitrary user-defined programs via configurable key
+ * bindings. The helper functions of \ref exec.c are called to execute both
+ * types of programs.
+ *
+ * The program also maintains a simple ring buffer, implemented in \ref
+ * ringbuffer.c, to remember recent command output.
+ */
+
+/** \cond doxygen_ignore */
 
 #include <signal.h>
 #include <sys/types.h>
@@ -21,7 +40,6 @@
 #include "sched.h"
 #include "signal.h"
 
-/** Array of error strings. */
 DEFINE_PARA_ERRLIST;
 
 static struct lls_parse_result *cmdline_lpr, *lpr;
@@ -40,7 +58,7 @@ static struct gui_window {
        bool needs_update;
 } top, bot, sb, in, sep;
 
-/** How many lines of output to remember. */
+/* How many lines of output to remember. */
 #define RINGBUFFER_SIZE 512
 
 struct rb_entry {
@@ -55,18 +73,18 @@ static pid_t exec_pid;
 static int exec_fds[2] = {-1, -1};
 static int loglevel;
 
-/** Type of the process currently being executed. */
+/* Type of the process currently being executed. */
 enum exec_status {
        EXEC_IDLE, /**< No process running. */
        EXEC_DCMD, /**< para or display process running. */
        EXEC_XCMD, /**< External process running. */
 };
 
-/**
+/*
  * Codes for various colors.
  *
- * Each status item has its own color pair. The ones defined here start at a
- * higher number so that they do not overlap with these.
+ * Each status item has its own color pair. The enumeration items defined here
+ * start at a higher number so that they do not overlap with the status items.
  */
 enum gui_color_pair {
        COLOR_STATUSBAR = NUM_STAT_ITEMS + 1,
@@ -138,7 +156,7 @@ struct status_task {
        int fd;
 };
 
-/** Stdout/stderr of the executing process is read in chunks of this size. */
+/* Stdout/stderr of the executing process is read in chunks of this size. */
 #define COMMAND_BUF_SIZE 32768
 
 struct exec_task {
@@ -180,7 +198,7 @@ static int get_num_cols(struct gui_window *w)
        return cols;
 }
 
-/** Number of lines of the window are occupied by an output line. */
+/* Number of lines of the window are occupied by an output line. */
 #define NUM_LINES(len) (1 + (len) / get_num_cols(&bot))
 
 /* isendwin() returns false before initscr() was called */
@@ -361,7 +379,8 @@ static int first_visible_rbe(unsigned *lines)
 }
 
 /*
-returns number of first visible rbe, *lines is the number of lines drawn.
+ * Returns the number of the first visible rbe. After the call, *lines is
+ * the number of lines drawn.
  */
 static int draw_top_rbe(unsigned *lines)
 {
@@ -496,7 +515,7 @@ static __printf_2_3 void curses_log(int ll, const char *fmt,...)
        va_end(ap);
 }
 
-/** The log function of para_gui, always set to curses_log(). */
+/* The log function of para_gui, always set to curses_log(). */
 __printf_2_3 void (*para_log)(int, const char *, ...) = curses_log;
 
 /* Call endwin() to reset the terminal into non-visual mode. */
@@ -1450,11 +1469,12 @@ static void handle_help_flags(void)
        exit(EXIT_SUCCESS);
 }
 
-/**
+/** \endcond
+ *
  * The main function of para_gui.
  *
- * \param argc Usual argument count.
- * \param argv Usual argument vector.
+ * \param argc Options are defined in the gui lopsub suite.
+ * \param argv The gui suite defines no subcommands.
  *
  * After initialization para_gui registers the following tasks to the paraslash
  * scheduler: status, exec, signal, input.
@@ -1473,7 +1493,7 @@ static void handle_help_flags(void)
  * The input task reads single key strokes from stdin. For each key pressed, it
  * executes the command handler associated with this key.
  *
- * \return \p EXIT_SUCCESS or \p EXIT_FAILURE.
+ * \return EXIT_SUCCESS or EXIT_FAILURE.
  */
 int main(int argc, char *argv[])
 {

diff --git a/play.c b/play.c
index d1cb59837a0fb60cda8fd32d8cc3becb397ac688..05dcaa2735e8dc0864a7e515fef941e3195873c8 100644 (file)
--- a/play.c
+++ b/play.c
@@ -1,6 +1,6 @@
 /* Copyright (C) 2012 Andre Noll <maan@tuebingen.mpg.de>, see file COPYING. */
 
-/** \file play.c Paraslash's standalone player
+/** \file play.c Standalone command line player.
  *
  * para_play(1) is an interactive tool to play audio files in a terminal.
  * It employs the buffer tree API to link together the afh receiver, a
@@ -8,11 +8,10 @@
  * all supported audio formats.
  *
  * Interactive command line editing is based on the API defined in \ref
- * interactive.h. Subcommands of para_play(1) are realized as lopsub
- * subcommands.
+ * interactive.h.
  */
 
-/** \cond */
+/** \cond doxygen_ignore */
 
 #include <signal.h>
 #include <lopsub.h>
@@ -1187,11 +1186,10 @@ static int play_post_monitor(__a_unused struct sched *s, __a_unused void *contex
  *
  * The main function of para_play(1).
  *
- * \param argc Command line options are parsed by the lopsub library.
+ * \param argc Options are defined in the play lopsub suite.
  *
- * \param argv Options are defined in the lopsub suite file of the source
- * tree (not part of the doxygen system). The suite file also contains the
- * definitions of the various subcommands (stop, pause, etc.).
+ * \param argv Subcommands (stop, pause, play, etc.) are realized as lopsub
+ * subcommands, and these are defined in the play suite file.
  *
  * para_play(1) distributes its work by submitting various tasks to the
  * paraslash scheduler. The receiver, filter and writer tasks, which are used