From: Andre Noll <maan@tuebingen.mpg.de>
Date: Mon, 2 Jan 2023 14:07:31 +0000 (+0100)
Subject: btr: Streamline the documentation of buffer_tree.h.
X-Git-Url: http://git.tue.mpg.de/?a=commitdiff_plain;h=d63f84b1a243ce5d0a7d13928d9f522d7f5b476b;p=paraslash.git

btr: Streamline the documentation of buffer_tree.h.

Nothing major, just a few minor English issues.
---

diff --git a/buffer_tree.h b/buffer_tree.h
index 5eb3d6e5..70fb3055 100644
--- a/buffer_tree.h
+++ b/buffer_tree.h
@@ -3,45 +3,43 @@
 /**
  * \file buffer_tree.h Buffer tree management.
  *
- * \par Buffer trees and buffer tree nodes.
- * The buffer tree API offers a more powerful method than standard unix pipes
- * for managing the data flow from the producer of the data (e.g. the network
- * receiver) to its consumer(s) (e.g. a sound card).
+ * Buffer trees and buffer tree nodes.
  *
- * A buffer tree consists of buffer tree nodes linked via certain parent/child
- * relationships.
+ * The buffer tree API offers an efficient method for managing the data flow
+ * from a producer (e.g. the network receiver) to the consumer(s) (e.g. a sound
+ * card).
+ *
+ * A buffer tree consists of buffer tree nodes which are linked together via
+ * parent/child relationships. Data buffers are propagated down without copying.
  *
  * Each data buffer starts its way from the root of the buffer tree. At each
  * node the data is investigated and possibly changed. New data is then fed to
- * each child.  Everything happens within one single-treaded process. There are
- * no file descriptors and no calls to read() or write().
+ * each child. There are no file descriptors, no processes/threads and no calls
+ * to read() or write().
  *
  * Whenever a node in the buffer tree creates output, either by creating a new
  * buffer or by pushing down buffers received from its parent, references to
- * that buffer are created for all children of the node. The buffer tree code
- * tries hard to avoid to copy buffer contents, but is forced to do so in case
- * there are alignment constraints.
+ * that buffer are created for all children of the node. The code avoids to
+ * copy buffer contents when possible.
  *
- * Communication between nodes is possible via the btr_exec_up() function.
- * For example, in para_audiod the alsa writer asks all parent nodes
- * for for the number of channels and the sample rate of the current
- * audio file.
+ * Communication between nodes is possible via the btr_exec_up() function. For
+ * example, in para_audiod the alsa writer asks all parent nodes for the number
+ * of channels and the sample rate of the current audio file.
  *
  * Buffer pools - An alternative to malloc/free buffer management.
  *
- * Non-leaf nodes usually create output to be processed by their children.  The
- * data must be fed through the output channel(s) of the node in order to make
- * that data available to each child.
+ * Non-leaf nodes usually create output to be processed by their child nodes.
+ * The data must be fed through the output channel(s) of the node in order to
+ * make that data available to each child.
  *
  * The easiest way to do so is to malloc() a buffer, fill it, and then call
  * btr_add_output(). This adds references to that buffer to all children. The
  * buffer is automatically freed if no buffer tree node is using it any more.
  *
- * This approach, while being simple, has some drawbacks, especially affecting
- * the root nodes of the buffer tree. Often the data source which is
- * represented by a root node does not know in advance how much data will be
- * available.  Therefore the allocated buffer is either larger than what can
- * currently be read, or is too small so that multiple buffers have to be used.
+ * This approach is simple but has some drawbacks. For example the data source
+ * represented by the root node does not know in advance how much data will be
+ * available. Therefore the allocated buffer will either be larger than
+ * necessary or too small so that multiple buffers have to be used.
  *
  * While this could be worked around by using a large buffer and calling
  * realloc() afterwards to shrink the buffer according to how much has been