Doxify para_gui.
authorAndre Noll <maan@systemlinux.org>
Sun, 16 Mar 2014 11:09:01 +0000 (12:09 +0100)
committerAndre Noll <maan@systemlinux.org>
Sun, 4 May 2014 13:48:55 +0000 (15:48 +0200)
Now that para_gui is in a much better shape, let's make it a first
class citizen and document all public functions and data structures.

Doxyfile
gui.c
gui.h
gui_theme.c

index 00cb6cc..239cd26 100644 (file)
--- a/Doxyfile
+++ b/Doxyfile
@@ -619,7 +619,6 @@ EXCLUDE_SYMLINKS       = NO
 # for example use the pattern */test/*
 
 EXCLUDE_PATTERNS       = *.cmdline.* \
-                         gui* \
                          gcc-compat.h \
                          fade.c \
                        *_command_list.h \
diff --git a/gui.c b/gui.c
index 4f536c5..9b7c2f9 100644 (file)
--- a/gui.c
+++ b/gui.c
@@ -35,7 +35,9 @@ static struct gui_window {
        bool needs_update;
 } top, bot, sb, in, sep;
 
+/** How many lines of output to remember. */
 #define RINGBUFFER_SIZE 512
+
 struct rb_entry {
        char *msg;
        size_t len;
@@ -51,10 +53,11 @@ static int exec_fds[2] = {-1, -1};
 static struct gui_args_info conf;
 static int loglevel;
 
+/** Type of the process currently being executed. */
 enum exec_status {
-       EXEC_IDLE, /* no command running */
-       EXEC_DCMD, /* para or display command running */
-       EXEC_XCMD, /* external command running */
+       EXEC_IDLE, /**< No process running. */
+       EXEC_DCMD, /**< para or display process running. */
+       EXEC_XCMD, /**< External process running. */
 };
 
 /**
@@ -132,6 +135,7 @@ struct status_task {
        int fd;
 };
 
+/** Stdout/stderr of the executing process is read in chunks of this size. */
 #define COMMAND_BUF_SIZE 32768
 
 struct exec_task {
@@ -497,6 +501,7 @@ static __printf_2_3 void curses_log(int ll, const char *fmt,...)
                vfprintf(stderr, fmt, ap);
        va_end(ap);
 }
+/** The log function of para_gui, always set to curses_log(). */
 __printf_2_3 void (*para_log)(int, const char*, ...) = curses_log;
 
 static void shutdown_curses(void)
@@ -1449,6 +1454,31 @@ static int setup_tasks_and_schedule(void)
        return schedule(&sched);
 }
 
+/**
+ * The main function of para_gui.
+ *
+ * \param argc Usual argument count.
+ * \param argv Usual argument vector.
+ *
+ * After initialization para_gui registers the following tasks to the paraslash
+ * scheduler: status, exec, signal, input.
+ *
+ * The status task executes the para_audioc stat command to obtain the status
+ * of para_server and para_audiod, and displays this information in the top
+ * window of para_gui.
+ *
+ * The exec task is responsible for printing the output of the currently
+ * running executable to the bottom window.
+ *
+ * The signal task performs suitable actions according to any signals received.
+ * For example it refreshes all windows on terminal size changes and resets the
+ * terminal on \p SIGTERM.
+ *
+ * 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.
+ */
 int main(int argc, char *argv[])
 {
        gui_cmdline_parser(argc, argv, &conf); /* exits on errors */
diff --git a/gui.h b/gui.h
index 13f5080..eabfd3c 100644 (file)
--- a/gui.h
+++ b/gui.h
@@ -6,32 +6,73 @@
 
 /** \file gui.h symbols used by gui and gui_theme */
 
+/** How to display one status item. */
 struct stat_item_data {
-       const char *prefix, *postfix;
-       unsigned x, y, len;
-       int fg, bg, align;
+       const char *prefix; /**< Text to print before the item content. */
+       const char *postfix; /**< Text to print after item content. */
+       unsigned x; /**< Horizontal start coordinate for this item. */
+       unsigned y; /**< Vertical start coordinate for this item. */
+       unsigned len; /**< Item width, including \a prefix and \a postfix. */
+       int fg; /**< Foreground color. */
+       int bg; /**< Background color. */
+       int align; /**< How to align this item. */
 };
 
+/** Theme definition. */
 struct gui_theme {
+       /** Printed at startup. */
        const char *name;
+       /** Also printed at startup. */
        const char *author;
-       int sb_fg, sb_bg;
-       int cmd_fg, cmd_bg;
-       int output_fg, output_bg;
-       int msg_fg, msg_bg;
-       int err_msg_fg, err_msg_bg;
-       int sep_fg, sep_bg;
+       /** Foreground color of the status bar. */
+       int sb_fg;
+       /** Background color of the status bar. */
+       int sb_bg;
+       /** Foreground for the name and args of the executing process. */
+       int cmd_fg;
+       /** Background for the name and args of the executing process. */
+       int cmd_bg;
+       /** Foreground color for stdout of the executing process. */
+       int output_fg;
+       /** Background color for stdout of the executing process. */
+       int output_bg;
+       /** Foreground color for log messages of moderate severity. */
+       int msg_fg;
+       /** Background color for log messages of moderate severity. */
+       int msg_bg;
+       /** Foreground color for severe log messages. */
+       int err_msg_fg;
+       /** Background color for severe log messages. */
+       int err_msg_bg;
+       /** Foreground color for the separator line. */
+       int sep_fg;
+       /** Background color for the separator line. */
+       int sep_bg;
+       /** The character for the separator line. */
        char sep_char;
-       int default_fg, default_bg;
-
-       int top_lines_default, top_lines_min;
-       int lines_min, cols_min;
+       /** Default foreground color, see assume_default_colors(3). */
+       int default_fg;
+       /** Default background color. */
+       int default_bg;
+       /** Default number of lines of the top window. */
+       int top_lines_default;
+       /** Minimal admissible number of lines to display the top window. */
+       int top_lines_min;
+       /** Minimal admissible number of lines to display this theme. */
+       int lines_min;
+       /** Minimal admissible number of columns to display this theme. */
+       int cols_min;
+       /** Individual status item properties. */
        struct stat_item_data data[NUM_STAT_ITEMS];
 };
 
 void theme_init(const char *name, struct gui_theme *t);
 void theme_prev(struct gui_theme *t);
 void theme_next(struct gui_theme *t);
+
+/** Status item text should be left-aligned. */
 #define LEFT 1
+/** Status item text should be right-aligned. */
 #define RIGHT 2
+/** Status item text should be displayed centered. */
 #define CENTER 3
index 3c9886d..b13fdf9 100644 (file)
@@ -4,6 +4,8 @@
  * Licensed under the GPL v2. For licencing details see COPYING.
  */
 
+/** \file gui_theme.c Theme definitions. */
+
 #include "para.h"
 #include "gui.h"
 #include <curses.h>
@@ -368,6 +370,7 @@ static struct theme_description themes[] = {
        },
 };
 
+/** Number of elements in the \a themes array. */
 #define NUM_THEMES (ARRAY_SIZE(themes))
 
 static int current_theme_num;
@@ -384,6 +387,14 @@ static void set_theme(int num, struct gui_theme *t)
        PARA_NOTICE_LOG("theme: %s\n", t->name);
 }
 
+/**
+ * Initialize a theme.
+ *
+ * \param name Name of the theme to be initialized.
+ * \param t The function fills out this structure.
+ *
+ * This function exits if there is no theme called \a name.
+ */
 void theme_init(const char *name, struct gui_theme *t)
 {
        int i;
@@ -399,11 +410,29 @@ void theme_init(const char *name, struct gui_theme *t)
        exit(EXIT_FAILURE);
 }
 
+/**
+ * Activate the previous available theme.
+ *
+ * \param t Theme definition is stored here.
+ *
+ * This picks the theme that comes before the currently active one, or the last
+ * availabe theme, if the current one is the first.
+ *
+ * \sa \ref theme_next().
+ */
 void theme_prev(struct gui_theme *t)
 {
        return set_theme(++current_theme_num, t);
 }
 
+/**
+ * Activate the next available theme.
+ *
+ * \param t Theme definition is stored here.
+ *
+ * This works exacly as theme_prev() but cycles forwards through the list of
+ * available themes.
+ */
 void theme_next(struct gui_theme *t)
 {
        return set_theme(--current_theme_num, t);