diff --git a/src/cluster/cluster.cpp b/src/cluster/cluster.cpp
index 92646598166084a8288f6343e7d76f94774a19bb..49e0c3b3e5585b36e762a8eb83a3b6a26e7f102f 100644
--- a/src/cluster/cluster.cpp
+++ b/src/cluster/cluster.cpp
@@ -1,4 +1,6 @@
/*! \file cluster.cpp
+ *
+ * \brief Implementation of the calculation for a cluster of spheres.
*/
#include <cstdio>
#include <complex>
diff --git a/src/cluster/np_cluster.cpp b/src/cluster/np_cluster.cpp
index 0af2b80f8bd8c3514084f30dc77b6fa38c49e909..73caa518f9d330b8ad4114a30f123ba320035756 100644
--- a/src/cluster/np_cluster.cpp
+++ b/src/cluster/np_cluster.cpp
@@ -1,4 +1,19 @@
-/*! \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";
diff --git a/src/include/Configuration.h b/src/include/Configuration.h
index 1050a61acaed2d6bf4754df2eeada5fe0ba68a36..bdf3e170afd0d1e4e07dbbd55aab52f16a70cdcc 100644
--- a/src/include/Configuration.h
+++ b/src/include/Configuration.h
@@ -1,4 +1,28 @@
/*! \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_
diff --git a/src/include/List.h b/src/include/List.h
index 0f9ebeab42e3e2e52d434e854420d061cd0c1d3a..8c51bd1ce7bb5816a48bd958c2c6656216e5a0fa 100644
--- a/src/include/List.h
+++ b/src/include/List.h
@@ -1,4 +1,6 @@
/*! \file List.h
+ *
+ * \brief A library of classes used to manage dynamic lists.
*/
#ifndef INCLUDE_LIST_H_
diff --git a/src/include/Parsers.h b/src/include/Parsers.h
index 94dd68e891b175c7263ca45585625e96122e0bf1..5b11d9f6a383f5c941be1912d20c0fa55860ae90 100644
--- a/src/include/Parsers.h
+++ b/src/include/Parsers.h
@@ -1,4 +1,7 @@
/*! \file Parsers.h
+ *
+ * \brief A library of functions designed to parse formatted input
+ * into memory.
*/
#ifndef FILE_NOT_FOUND_ERROR
diff --git a/src/libnptm/Commons.cpp b/src/libnptm/Commons.cpp
index 8031eaad68f3127546b222eb3d0e62bff6f5e0be..81cb853bfcb1f757cab084a1f587a620c9b14f0d 100644
--- a/src/libnptm/Commons.cpp
+++ b/src/libnptm/Commons.cpp
@@ -1,14 +1,14 @@
/*! \file Commons.cpp
*
- * DEVELOPMENT NOTE:
- * The construction of common blocks requires some information
- * 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
- * to the configuration objects. These, on their turn, need to
- * expose methods to access the relevant data in read-only mode.
+ * DEVELOPMENT NOTE:
+ * The construction of common blocks requires some information
+ * 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 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.
*/
#include <complex>
diff --git a/src/libnptm/Configuration.cpp b/src/libnptm/Configuration.cpp
index 5d1c05d898179cca789efc59061ee3600a8a899c..069315225998f3ef03e0fdb11371524993db584f 100644
--- a/src/libnptm/Configuration.cpp
+++ b/src/libnptm/Configuration.cpp
@@ -1,4 +1,6 @@
/*! \file Configuration.cpp
+ *
+ * \brief Implementation of the configuration classes.
*/
#include <cmath>
diff --git a/src/libnptm/Parsers.cpp b/src/libnptm/Parsers.cpp
index a327df810c95b58e3c0e94cfe207f104d482a5bd..3f8c9ff5116126b909baa9b7755f9bad09659642 100644
--- a/src/libnptm/Parsers.cpp
+++ b/src/libnptm/Parsers.cpp
@@ -1,4 +1,6 @@
/*! \file Parsers.cpp
+ *
+ * \brief Implementation of the parsing functions.
*/
#include <fstream>
diff --git a/src/sphere/np_sphere.cpp b/src/sphere/np_sphere.cpp
index 1846b36973859d1a175d2ff7f579ed1de064b6fe..e3033dae6fa36f373e17c1fda92f802537ce3b53 100644
--- a/src/sphere/np_sphere.cpp
+++ b/src/sphere/np_sphere.cpp
@@ -1,4 +1,19 @@
/*! \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,16 +34,20 @@ 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";
- string data_file = "../../test_data/sphere/DSPH";
- string output_path = ".";
- if (argc == 4) {
- config_file = string(argv[1]);
- data_file = string(argv[2]);
- output_path = string(argv[3]);
- }
- sphere(config_file, data_file, output_path);
- return 0;
+ string config_file = "../../test_data/sphere/DEDFB";
+ string data_file = "../../test_data/sphere/DSPH";
+ string output_path = ".";
+ if (argc == 4) {
+ config_file = string(argv[1]);
+ data_file = string(argv[2]);
+ output_path = string(argv[3]);
+ }
+ sphere(config_file, data_file, output_path);
+ return 0;
}
diff --git a/src/sphere/sphere.cpp b/src/sphere/sphere.cpp
index 2e179fc59ecb5aaff9e23f68a6a2494757a632e8..f3264ce867404ce120770ca43759ebf5592c172f 100644
--- a/src/sphere/sphere.cpp
+++ b/src/sphere/sphere.cpp
@@ -1,4 +1,6 @@
/*! \file sphere.cpp
+ *
+ * \brief Implementation of the single sphere calculation.
*/
#include <cstdio>
#include <fstream>
diff --git a/src/trapping/cfrfme.cpp b/src/trapping/cfrfme.cpp
index fd7c342083a557c2718ed41c7c3b617593649f75..f5d7af1cfefb7a5a1d41591962acbc9fbf3a0ae4 100644
--- a/src/trapping/cfrfme.cpp
+++ b/src/trapping/cfrfme.cpp
@@ -1,4 +1,6 @@
-/*! \file frfme.cpp
+/*! \file cfrfme.cpp
+ *
+ * C++ implementation of FRFME functions.
*/
#include <complex>
#include <cstdio>
diff --git a/src/trapping/clffft.cpp b/src/trapping/clffft.cpp
index e9c1f42147d42c4db1b1cac7ee978649bf582337..9cd9b50b409b48383fb02d74983ef761a5c71506 100644
--- a/src/trapping/clffft.cpp
+++ b/src/trapping/clffft.cpp
@@ -1,4 +1,6 @@
-/*! \file lffft.cpp
+/*! \file clffft.cpp
+ *
+ * \brief C++ implementation of LFFFT functions.
*/
#include <complex>
#include <cstdio>
diff --git a/src/trapping/np_trapping.cpp b/src/trapping/np_trapping.cpp
index cb3d9be08dbdbb8d0e374039d6fd7ba90f336b5c..236013a77f4e65254139589dcd957e7467b0cd88 100644
--- a/src/trapping/np_trapping.cpp
+++ b/src/trapping/np_trapping.cpp
@@ -1,4 +1,6 @@
-/*! \file trapping.cpp
+/*! \file np_trapping.cpp
+ *
+ * \brief Trapping problem handler.
*/
#include <cstdio>
#include <string>