Tweak documentation of main and scda

doc/mainpage.dox

@@ -35,15 +35,16 @@
  *    reside in the config/ subdirectory.  These are used in sc but also
  *    available to other projects for convenience.  It is possible to nest
  *    packages this way.
+ *  * CMake support has been added and is still in development.
  *  * The library provides MPI wrappers in case it is configured without
- *    MPI.  They implement initialize/finalize and collective calls as
- *    noops, which means that these do not have to be protected with the
- *    \#ifdef SC_MPI construct in the code.
+ *    MPI (the default).  They implement initialize/finalize and collective
+ *    calls as noops, which means that these do not have to be protected
+ *    with the \#ifdef SC_MPI construct in the code.
  *  * The library provides a logging framework that can be adapted by other
  *    packages.  Multiple log levels are available, as well as options to
- *    output on just one or all MPI processes.
+ *    output on just one or all MPI processes and to customize the style.
  *  * The library provides a set of data containers, such as dynamically
- *    resizable arrays.
+ *    resizable arrays and memory pools.
  *
  * To build the sc library from a tar distribution, use the standard
  * procedure of the GNU autotools.  The configure script takes the following
@@ -52,17 +53,18 @@
  * * `--enable-debug`   lowers the log level for increased verbosity and
  *                    activates the `SC_ASSERT` macro for consistency checks.
  * * `--enable-mpi`     pulls in the mpi.h include file and activates the MPI
- *                    compiler wrappers.  If this option is not given, wrappers
- *                    for MPI routines are used instead and the code is compiled
- *                    in serial only.
+ *                    compiler wrappers.  If this option is not given, trivial
+ *                    wrappers for MPI routines are activated and the code
+ *                    is expected to be executed in serial only.
  * * `--disable-mpiio`  may be used to avoid using `MPI_File` based calls. The
-                      usage of `--disable-mpiio` is deprecated and should not be
-                      used anymore.
+ *                    usage of `--disable-mpiio` is deprecated and should not be
+ *                    used anymore.
  *
  * A typical development configure line looks as follows:
  * > `relative/path/to/configure CFLAGS="-Wall -O0 -g" --enable-mpi --enable-debug`
  * A typical production configure line looks as follows:
  * > `relative/path/to/configure CFLAGS="-Wall -O2" --enable-mpi`
+ * To specify a path for `make install` add a `--prefix=<installdir>` option.
  *
  * \see https://www.p4est.org/
  * \see https://www.gnu.org/licenses/licenses.html
@@ -97,4 +99,4 @@
  * We elaborate further on the workflow in \ref scda_workflow .
  *
  * \ingroup sc
- */
+ */

doc/release_notes.txt

@@ -22,6 +22,7 @@
  - Add sc_MPI_Aint and sc_MPI_Aint_diff
  - Add sc_MPI_UNSIGNED_LONG_LONG, sc_MPI_SIGNED_CHAR and sc_MPI_INT8_T
  - Implement a functional subset of the scda API for parallel I/O
+ - Intremental documentation updates
 
 ### Build system
 

src/sc_scda.h

@@ -165,18 +165,18 @@
  * All workflows start with \ref sc_scda_fopen_write or \ref sc_scda_fopen_read
  * that creates a file context \ref sc_scda_fcontext_t that never moves backwards.
  *
- * Then the user can call a sequence of functions out of:
+ * Then the user may call any combination of functions out of:
  *
  * - \ref sc_scda_fwrite_inline,
  * - \ref sc_scda_fwrite_block,
  * - \ref sc_scda_fwrite_array and
  * - \ref sc_scda_fwrite_varray,
  *
- * for the case of using \ref sc_scda_fopen_write.
+ * for a context obtained from \ref sc_scda_fopen_write.
  *
- * Alternatively, for using \ref sc_scda_fopen_read the user must call
+ * Alternatively, after using \ref sc_scda_fopen_read the user must call
  * \ref sc_scda_fread_section_header that examines the current file section
- * and then call accordingly to the retrieved file section type
+ * and then call accordingly to the retrieved file section type one of
  *
  * - \ref sc_scda_fread_inline_data,
  * - \ref sc_scda_fread_block_data,
@@ -188,11 +188,11 @@
  * sc_scda_fclose.
  *
  * All above mentioned sc_scda functions are collective and output an
- * error code (cf. \ref sc_scda_ferror_t) that can be examined by \ref
+ * error code (cf. \ref sc_scda_ferror_t) that can be translated by \ref
  * sc_scda_ferror_string.
  *
- * For more details and the option for encoded data see the functions
- * in \ref sc_scda.h.
+ * For more details and the option for encoding metadata and data see the
+ * functions in \ref sc_scda.h.
  */
 
 #ifndef SC_SCDA_H