Update entry documentation of all C++ source code files

src/cluster/cluster.cpp

 /*! \file cluster.cpp
+ *
+ * \brief Implementation of the calculation for a cluster of spheres.
  */
 #include <cstdio>
 #include <complex>

src/cluster/np_cluster.cpp

-/*! \file np_sphere.cpp
+/*! \file np_cluster.cpp
+ *
+ * \brief Cluster of spheres scattering problem handler.
+ *
+ * This program emulates the execution work-flow originally handled by the
+ * FORTRAN EDFB and CLU codes, which undertook the task of solving the
+ * scattering calculation for the case of a cluster of spheres, with one or
+ * more materials. The program is designed to work in two modes: emulation and
+ * enhanced. The emulation mode is activated by invoking the program without
+ * arguments. In this case, the code looks for hard-coded default input and
+ * writes output in the execution folder, replicating the behaviour of the
+ * original FORTRAN code. Advanced mode, instead, is activated by passing
+ * command line arguments that locate the desired input files and a valid
+ * folder to write the output into. The emulation mode is useful for testing,
+ * while the advanced mode implements the possibility to change input and
+ * output options, without having to modify the code.
  */
 
 #include <cstdio>
@@ -20,6 +35,10 @@ extern void cluster(string config_file, string data_file, string output_path);
  * or some otherwise formatted configuration data set. The code can be
  * linked to a luncher script or to a GUI oriented application that performs
  * the configuration and runs the main program.
+ *
+ * \param argc: `int` The number of arguments given in command-line.
+ * \param argv: `char **` The vector of command-line arguments.
+ * \return result: `int` An exit code passed to the OS (0 for succesful execution).
  */
 int main(int argc, char **argv) {
   	string config_file = "../../test_data/cluster/DEDFB";

src/include/Configuration.h

 /*! \file Configuration.h
+ *
+ * \brief Configuration data structures.
+ *
+ * To handle the calculation of a scattering problem, the code needs a set
+ * of configuration parameters that define the properties of the scattering
+ * particle, of the incident radiation field and of the geometry of the
+ * problem. The necessary information is managed through the use of two
+ * classes: `ScattererConfiguration` and `GeometryConfiguration`. The first
+ * class, `ScattererConfiguration`, undertakes the role of describing the
+ * scattering particle properties, by defining its structure in terms of a
+ * distribution of spherical sub-particles, and the optical properties of
+ * the constituting materials. It also defines the scaling vector, which
+ * tracks the ratio of particle size and radiation wavelength, eventually
+ * allowing for the iteration of the calculation on different wavelengths.
+ * Multiple materials and layered structures are allowed, while sphere
+ * compenetration is not handled, due to the implied discontinuity on the
+ * spherical symmetry of the elementary sub-particles. The second class,
+ * `GeometryConfiguration`, on the contrary, describes the properties of
+ * the radiation field impinging on the particle. It defines the incoming
+ * radiation polarization state, the incident direction and the scattering
+ * directions that need to be accounted for. Both classes expose methods to
+ * read the required configuration data from input files formatted according
+ * to the same rules expected by the original code. In addition, they offer
+ * perform I/O operations towards proprietary and standard binary formats.
  */
 
 #ifndef INCLUDE_CONFIGURATION_H_

src/include/List.h

 /*! \file List.h
+ *
+ * \brief A library of classes used to manage dynamic lists.
  */
 
 #ifndef INCLUDE_LIST_H_

src/include/Parsers.h

 /*! \file Parsers.h
+ *
+ * \brief A library of functions designed to parse formatted input
+ * into memory.
  */
 
 #ifndef FILE_NOT_FOUND_ERROR

src/libnptm/Commons.cpp

@@ -5,8 +5,8 @@
  * that is stored in configuration objects and is needed to compute
  * the allocation size of vectors and matrices. Currently, this
  * information is passed as arguments to the constructors of the
- *	common blocks. A simpler and more logical way to operate is
- *	to design the constructors to take as arguments only pointers
+ * common blocks. A simpler and more logical way to operate would
+ * be to design the constructors to take as arguments only pointers
  * to the configuration objects. These, on their turn, need to
  * expose methods to access the relevant data in read-only mode.
  */

src/libnptm/Configuration.cpp

 /*! \file Configuration.cpp
+ *
+ * \brief Implementation of the configuration classes.
  */
 
 #include <cmath>

src/libnptm/Parsers.cpp

 /*! \file Parsers.cpp
+ *
+ * \brief Implementation of the parsing functions.
  */
 
 #include <fstream>

src/sphere/np_sphere.cpp

 /*! \file np_sphere.cpp
+ *
+ * \brief Single sphere scattering problem handler.
+ *
+ * This program emulates the execution work-flow originally handled by the
+ * FORTRAN EDFB and SPH codes, which undertook the task of solving the
+ * scattering calculation for the case of a single, possibly multi-layered
+ * sphere. The program is designed to work in two modes: emulation and
+ * enhanced. The emulation mode is activated by invoking the program without
+ * arguments. In this case, the code looks for hard-coded default input and
+ * writes output in the execution folder, replicating the behaviour of the
+ * original FORTRAN code. Advanced mode, instead, is activated by passing
+ * command line arguments that locate the desired input files and a valid
+ * folder to write the output into. The emulation mode is useful for testing,
+ * while the advanced mode implements the possibility to change input and
+ * output options, without having to modify the code.
  */
 #include <complex>
 #include <cstdio>
@@ -19,6 +34,10 @@ extern void sphere(string config_file, string data_file, string output_path);
  * or some otherwise formatted configuration data set. The code can be
  * linked to a luncher script or to a GUI oriented application that performs
  * the configuration and runs the main program.
+ *
+ * \param argc: `int` The number of arguments given in command-line.
+ * \param argv: `char **` The vector of command-line arguments.
+ * \return result: `int` An exit code passed to the OS (0 for succesful execution).
  */
 int main(int argc, char **argv) {
   string config_file = "../../test_data/sphere/DEDFB";

src/sphere/sphere.cpp

 /*! \file sphere.cpp
+ *
+ * \brief Implementation of the single sphere calculation.
  */
 #include <cstdio>
 #include <fstream>

src/trapping/cfrfme.cpp

-/*! \file frfme.cpp
+/*! \file cfrfme.cpp
+ *
+ * C++ implementation of FRFME functions.
  */
 #include <complex>
 #include <cstdio>

src/trapping/clffft.cpp

-/*! \file lffft.cpp
+/*! \file clffft.cpp
+ *
+ * \brief C++ implementation of LFFFT functions.
  */
 #include <complex>
 #include <cstdio>

src/trapping/np_trapping.cpp

-/*! \file trapping.cpp
+/*! \file np_trapping.cpp
+ *
+ * \brief Trapping problem handler.
  */
 #include <cstdio>
 #include <string>