From: Andre Noll <maan@tuebingen.mpg.de>
Date: Sat, 31 May 2025 19:02:19 +0000 (+0200)
Subject: dox
X-Git-Url: https://git.tuebingen.mpg.de/?a=commitdiff_plain;h=ae2662ecab94bfa53c70a6d0daf1502879f0fa04;p=paraslash.git

dox
---

diff --git a/client.c b/client.c
index a5a8af53..6f28a25b 100644
--- a/client.c
+++ b/client.c
@@ -1,6 +1,14 @@
 /* Copyright (C) 1997 Andre Noll <maan@tuebingen.mpg.de>, see file COPYING. */
 
-/** \file client.c The client program used to connect to para_server. */
+/** \file client.c The client program used to connect to para_server.
+ *
+ * The bulk of the code of this file is the completers because interactive
+ * sessions are implemented in \ref interactive.c and the autentication
+ * handshake (shared with para_audiod(1)) is implemented in \ref
+ * client_common.c. This file contains no non-static functions except main().
+ */
+
+/** \cond */
 
 #include <signal.h>
 #include <lopsub.h>
@@ -17,7 +25,6 @@
 #include "buffer_tree.h"
 #include "error.h"
 
-/** Array of error strings. */
 DEFINE_PARA_ERRLIST;
 
 static struct sched sched;
@@ -607,13 +614,21 @@ static int supervisor_post_monitor(struct sched *s, void *context)
 
 static struct supervisor_task supervisor_task;
 
-/**
+/** \endcond
+ *
  * The client program to connect to para_server.
  *
- * \param argc Usual argument count.
- * \param argv Usual argument vector.
+ * \param argc Options are defined in the client lopsub suite.
+ * \param argv The client suite defines no subcommands.
+ *
+ * If --complete is specified, possible completions are determined by executing
+ * a second instance of para_client(1). For example, if attribute completion
+ * is needed, the lsatt server subcommand is run.
+ *
+ * If run with no arguments, an interactive session is started. In this
+ * case we call \ref i9e_open() of \ref interactive.c, which implements
+ * interactive sessions, including command line editing and tab completion.
  *
- * When called without a paraslash command, an interactive session is started.
  * Otherwise, the client task and the supervisor task are started. The former
  * communicates with para_server while the latter monitors whether the client
  * task intends to read from stdin or write to stdout.
diff --git a/play.c b/play.c
index 304b1d23..d1cb5983 100644
--- a/play.c
+++ b/play.c
@@ -2,7 +2,7 @@
 
 /** \file play.c Paraslash's standalone player
  *
- * The para_play(1) is an interactive tool to play audio files in a terminal.
+ * 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
  * decoder and the default writer (alsa on linux), enabling playback for
  * all supported audio formats.
@@ -10,8 +10,9 @@
  * Interactive command line editing is based on the API defined in \ref
  * interactive.h. Subcommands of para_play(1) are realized as lopsub
  * subcommands.
- *
- * \cond doxygen_ignore */
+ */
+
+/** \cond */
 
 #include <signal.h>
 #include <lopsub.h>
@@ -1182,7 +1183,7 @@ static int play_post_monitor(__a_unused struct sched *s, __a_unused void *contex
 	return 1;
 }
 
-/** \endcond doxygen_ignore
+/** \endcond
  *
  * The main function of para_play(1).
  *
diff --git a/web/documentation.in.html b/web/documentation.in.html
index 4d9aea6a..9c58221f 100644
--- a/web/documentation.in.html
+++ b/web/documentation.in.html
@@ -38,15 +38,15 @@ Reference</a>. Suggested entry points: </p>
 	<li> Executables:
 		[<a href="doxygen/html/server_8c.html">para_server</a>]
 		[<a href="doxygen/html/audiod_8c.html">para_audiod</a>]
-		[<a href="doxygen/html/play_8c.html">para_play</a>]
-		[<a href="doxygen/html/recv_8c.html">para_recv</a>]
-		[<a href="doxygen/html/filter_8c.html">para_filter</a>]
-		[<a href="doxygen/html/write_8c.html">para_write</a>]
 		[<a href="doxygen/html/client_8c.html">para_client</a>]
 		[<a href="doxygen/html/audioc_8c.html">para_audioc</a>]
 		[<a href="doxygen/html/afh_8c.html">para_afh</a>]
-		[<a href="doxygen/html/mixer_8c.html">para_mixer</a>]
+		[<a href="doxygen/html/recv_8c.html">para_recv</a>]
+		[<a href="doxygen/html/filter_8c.html">para_filter</a>]
+		[<a href="doxygen/html/write_8c.html">para_write</a>]
 		[<a href="doxygen/html/gui_8c.html">para_gui</a>]
+		[<a href="doxygen/html/mixer_8c.html">para_mixer</a>]
+		[<a href="doxygen/html/play_8c.html">para_play</a>]
 	</li> <li> Subsystems:
 		[<a href="doxygen/html/sched_8h.html">Scheduler</a>]
 		[<a href="doxygen/html/buffer__tree_8h.html">Buffer Trees</a>]