Doxify para_gui.

[paraslash.git] / gui.c

diff --git a/gui.c b/gui.c
index 4f536c5d193fff1e98f4e442df86b1d5d00a5156..9b7c2f992520896f2ae33918854604b37bbc7720 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 */