From 116b57fd91c00b74a7899caf74741be1cdaa0f8c Mon Sep 17 00:00:00 2001
From: Giovanni La Mura <giovanni.lamura@inaf.it>
Date: Fri, 19 Jan 2024 11:37:57 +0100
Subject: [PATCH] Update entry documentation of all C++ source code files
---
src/cluster/cluster.cpp | 2 ++
src/cluster/np_cluster.cpp | 21 ++++++++++++++++++-
src/include/Configuration.h | 24 +++++++++++++++++++++
src/include/List.h | 2 ++
src/include/Parsers.h | 3 +++
src/libnptm/Commons.cpp | 18 ++++++++--------
src/libnptm/Configuration.cpp | 2 ++
src/libnptm/Parsers.cpp | 2 ++
src/sphere/np_sphere.cpp | 39 ++++++++++++++++++++++++++---------
src/sphere/sphere.cpp | 2 ++
src/trapping/cfrfme.cpp | 4 +++-
src/trapping/clffft.cpp | 4 +++-
src/trapping/np_trapping.cpp | 4 +++-
13 files changed, 104 insertions(+), 23 deletions(-)
diff --git a/src/cluster/cluster.cpp b/src/cluster/cluster.cpp
index 92646598..49e0c3b3 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 0af2b80f..73caa518 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 1050a61a..bdf3e170 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 0f9ebeab..8c51bd1c 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 94dd68e8..5b11d9f6 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 8031eaad..81cb853b 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 5d1c05d8..06931522 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 a327df81..3f8c9ff5 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 1846b369..e3033dae 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 2e179fc5..f3264ce8 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 fd7c3420..f5d7af1c 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 e9c1f421..9cd9b50b 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 cb3d9be0..236013a7 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>
--
GitLab