[spo] draft-731: Update documentation to recent pipeline changes

- describe packet read modes (fetch, peek) and status codes
- describe new design of frames (pools, partial reads)
- describe frame read modes (hard, soft) and codes
- describe frame fields and formats

docs/sphinx/development/coding_guidelines.rst

@@ -37,9 +37,7 @@ Portability
 
 * The code should run on a variety of operating systems, compilers, and hardware architectures, including rather old compilers and distributions. See :doc:`supported platforms </portability/supported_platforms>` page.
 
-.. raw:: html
-
-    <span></span>
+\
 
 * The code specific to platform, compiler, or optional features and dependencies, should be isolated inside corresponding :ref:`target directories <targets>`. All other code should be portable across all supported configurations.
 
@@ -48,57 +46,39 @@ Best practices
 
 * The code should compile without warnings. Use ``--enable-werror`` :doc:`option </building/scons_options>` to turn warnings into errors.
 
-.. raw:: html
-
-    <span></span>
+\
 
 * Cover every component with class-level unit tests if possible. Additionally, cover high-level features with pipeline-level integration tests. We use `CppUTest <https://cpputest.github.io/>`_.
 
-.. raw:: html
-
-    <span></span>
+\
 
 * Prefer RAII and smart pointers for resource management.
 
-.. raw:: html
-
-    <span></span>
+\
 
 * Prefer either non-copyable or trivial-copy objects. Avoid making "heavy" operations implicit, in particular, operations involving memory management.
 
-.. raw:: html
-
-    <span></span>
+\
 
 * Use ``const`` when it's useful.
 
-.. raw:: html
-
-    <span></span>
+\
 
 * Use anonymous namespaces instead of static globals, functions, and constants.
 
-.. raw:: html
-
-    <span></span>
+\
 
 * Use enums instead of defines, when possible.
 
-.. raw:: html
-
-    <span></span>
+\
 
 * Use arenas and pools for memory management.
 
-.. raw:: html
-
-    <span></span>
+\
 
 * Carefully log (using ``roc_log``) all important events and information needed to understand why an error occurred.
 
-.. raw:: html
-
-    <span></span>
+\
 
 * Panic (using ``roc_panic``) when a contract or an invariant is broken. A panic is always preferred over a crash or undefined behavior. However, remember that panics are only for bugs in Roc itself. Never panic on invalid or unexpected data from the outside world.
 
@@ -107,33 +87,23 @@ Coding style
 
 * The code should be formatted using ``scons fmt``, which invokes ``clang-format``. If it goes awry, you can prevent a file from being formatted by adding it to ``.fmtignore``.
 
-.. raw:: html
-
-    <span></span>
+\
 
 * Header and source files should contain the "Roc Streaming authors" copyright and license header. Running ``scons fmt`` will automatically insert them.
 
-.. raw:: html
-
-    <span></span>
+\
 
 * Headers, classes, public members, and free functions should be documented using Doxygen. Use ``--enable-doxygen`` :doc:`option </building/scons_options>` to enable warnings about undocumented elements.
 
-.. raw:: html
-
-    <span></span>
+\
 
 * Prefer creating individual .h and .cpp files for every class. Use snake_case for file names and old-style header guards, which are automatically inserted by ``scons fmt``.
 
-.. raw:: html
-
-    <span></span>
+\
 
 * Use upper case SNAKE_CASE for macros, CamelCase for class names, and lower case snake_case for methods, functions, fields, and variables. Add trailing underscore\_ for private methods and fields.
 
-.. raw:: html
-
-    <span></span>
+\
 
 * Members in class should have the following order:
 
@@ -150,9 +120,7 @@ Coding style
      * methods
      * fields
 
-.. raw:: html
-
-    <span></span>
+\
 
 * The code should be formatted according to our 1TBS-like indentation style defined in ``.clang-format`` config:
 
@@ -161,12 +129,6 @@ Coding style
   * use braces even for single-statement blocks;
   * don't place condition or loop bodies at the same line as the control statement.
 
-.. raw:: html
-
-    <span></span>
+\
 
 * ``#endif`` and ``#else`` statements should have trailing ``// <NAME>`` and ``// !<NAME>`` comments. Namespace closing brace should have trailing ``// namespace <name>`` comment.
-
-.. raw:: html
-
-    <span></span>

docs/sphinx/internals/audio_backends.rst

@@ -20,7 +20,7 @@ syntax                     meaning                    example
 ``file://-`` or ``file:-`` stdin or stdout            ``file:-``
 ========================== ========================== ==============
 
-User can specify input file/device (**source**) for ``roc-send`` via ``--input`` option, and output file/device (**sink**) for ``roec-recv`` via ``--output`` option.
+User can specify input file/device (**source**) for ``roc-send`` via ``--input`` option, and output file/device (**sink**) for ``roc-recv`` via ``--output`` option.
 
 When device is used, user specifies driver explicitly (e.g. ``alsa://`` for ALSA, ``pulse://`` for PulseAudio, etc). When file is used, file driver is selected automatically, usually by file extension. However, user may force usage of specific driver for the file via ``--input-format`` or ``--output-format`` option.
 
@@ -45,7 +45,7 @@ The job of ``roc-send`` and ``roc-recv`` is thus to open a source and a sink and
 
 - in ``roc-recv``, ``ISource`` is implemented by receiver pipeline from ``roc_pipeline``, and ``ISink`` is implemented by device or file from ``roc_sndio``
 
-The task of transferring sound from ``ISource`` to ``ISink`` is implemented in `sndio::Pump <https://roc-streaming.org/toolkit/doxygen/classroc_1_1sndio_1_1Pump.html>`_ class, which works uniformely with any pair of source and sink, being it file, device, or pipeline.
+The task of transferring sound from ``ISource`` to ``ISink`` is implemented in `sndio::Pump <https://roc-streaming.org/toolkit/doxygen/classroc_1_1sndio_1_1Pump.html>`_ class, which works uniformly with any pair of source and sink, being it file, device, or pipeline.
 
 Backends and drivers
 ====================
@@ -56,7 +56,7 @@ Every **backend** (`IBackend <https://roc-streaming.org/toolkit/doxygen/classroc
 
 For example, SoxBackend (backend that implements audio I/O using SoX library) implements several device and file drivers: ``alsa``, ``pulse``, ``mp3``, etc. Every device driver corresponds to particular sound system (e.g. ALSA, PulseAudio), and every file driver corresponds to particular file format (e.g. MP3).
 
-When user asks backend dispatcher to open sink or source, user speicifies I/O URI and, for files, optional file format (i.e. driver name). Backend dispatcher then finds backend which is able to handle given device or file and asks it to create its implementation of ``ISource`` or ``ISink``.
+When user asks backend dispatcher to open sink or source, user specifies I/O URI and, for files, optional file format (i.e. driver name). Backend dispatcher then finds backend which is able to handle given device or file and asks it to create its implementation of ``ISource`` or ``ISink``.
 
 To help backend dispatcher with making decision, backends provide **driver information** about every available driver:
 

docs/sphinx/internals/code_structure.rst

@@ -131,6 +131,7 @@ target_libuv          Enabled if libuv is available
 target_openfec        Enabled if OpenFEC is available
 target_speexdsp       Enabled if SpeexDSP is available
 target_sox            Enabled if SoX is available
+target_sndfile        Enabled if libsndfile is available
 target_pulseaudio     Enabled if PulseAudio is available
 target_nobacktrace    Enabled if no backtrace API is available
 target_nodemangle     Enabled if no demangling API is available

docs/sphinx/internals/glossary.rst

@@ -10,7 +10,7 @@ Participants
 
 .. glossary::
 
-*roc node*
+*roc peer*
     A sender or receiver (see below).
 
 *roc sender*
@@ -23,10 +23,10 @@ Participants
     An entity that corresponds to one sender connected to one receiver.
 
 *roc sender session*
-    Represenation of roc session on sender side.
+    Representation of roc session on sender side.
 
 *roc receiver session*
-    Represenation of roc session on receiver side.
+    Representation of roc session on receiver side.
 
 Audio
 =====