From: Andre Noll <maan@tuebingen.mpg.de>
Date: Mon, 9 Jun 2025 15:39:01 +0000 (+0200)
Subject: write
X-Git-Url: https://git.tuebingen.mpg.de/?a=commitdiff_plain;h=936aed705107ab46a4a24df0da0a92f0f1015940;p=paraslash.git

write
---

diff --git a/recv.c b/recv.c
index f5942d36..139e9bac 100644
--- a/recv.c
+++ b/recv.c
@@ -54,15 +54,14 @@ static void handle_help_flag(struct lls_parse_result *lpr)
 	exit(EXIT_SUCCESS);
 }
 
-/** \endcond doxygen_ignore
+/** \endcond
  *
- * The main function of para_recv.
+ * The main function of para_recv(1).
  *
- * \param argc Command line options are parsed by the lopsub library.
+ * \param argc Options are defined in the recv lopsub suite.
  *
- * \param argv Options are defined in the lopsub suite file of the source tree
- * (not part of the doxygen system). A separate suite file defines the options
- * of the receivers where each receiver corresponds to a lopsub subcommand.
+ * \param argv The recv_cmd suite file defines the various receivers and their
+ * options. Each receiver corresponds to a lopsub subcommand of this suite.
  *
  * para_recv receives an audio stream and writes received it to stdout.
  * If the afh receiver is specified, the stream is "received" from a local
diff --git a/write.c b/write.c
index 1cdfbc0f..e7aacf67 100644
--- a/write.c
+++ b/write.c
@@ -1,6 +1,14 @@
 /* Copyright (C) 2005 Andre Noll <maan@tuebingen.mpg.de>, see file COPYING. */
 
-/** \file write.c Paraslash's standalone wav/raw player. */
+/** \file write.c Paraslash's standalone wav/raw player.
+ *
+ * This file contains the main function of para_write(1), which is conceptually
+ * similar to para_recv(1) in that it employs the scheduler and sets up a
+ * simple buffer tree. The tree combines the stdin buffer tree node with
+ * one of the paraslash writers. Besides the writers, the check_wav object
+ * is also linked into the executable.
+ *
+ * \cond doxygen_ignore */
 
 #include <sys/types.h>
 #include <lopsub.h>
@@ -18,7 +26,6 @@
 #include "error.h"
 #include "check_wav.h"
 
-/** Array of error strings. */
 DEFINE_PARA_ERRLIST;
 
 #define CMD_PTR (lls_cmd(0, write_suite))
@@ -124,16 +131,24 @@ static int setup_and_schedule(struct lls_parse_result *lpr)
 	return ret;
 }
 
-/**
- * Para_write's main function.
+/** \endcond
+ *
+ * The main function of para_write(1).
+ *
+ * \param argc Options are defined in the write lopsub suite.
  *
- * \param argc The usual argument counter.
- * \param argv The usual argument vector.
+ * \param argv The write_cmd suite file defines the various writers and their
+ * options. Each writer corresponds to a lopsub subcommand of this suite.
  *
- * It sets up and starts the tasks and the buffer tree nodes determined by
- * command line options.
+ * Set up the stdin task, the check_wav task and the writer task, and combine
+ * the corresponding buffer tree nodes to form a chain. The check wav task
+ * becomes active as soon as the first chunk of data is read from stdin. If
+ * the data looks like a wav header, the check_wav task parses the header,
+ * and passes through subsequent data, waiting for the writer task calling
+ * \ref btr_exec_up() to query the number of channels, the sample rate and
+ * the sample format.
  *
- * \return \p EXIT_SUCCESS or EXIT_FAILURE
+ * \return EXIT_SUCCESS or EXIT_FAILURE
  */
 int main(int argc, char *argv[])
 {