Expand documentation for TransitionMatrix class

src/include/TransitionMatrix.h

@@ -48,6 +48,9 @@ class TransitionMatrix {
   int *shape;
 
   /*! \brief Build transition matrix from a HDF5 binary input file.
+   *
+   * This function takes care of the specific task of building a transition
+   * matrix memory data structure from a HDF5 binary input file.
    *
    * \param file_name: `string` Name of the binary configuration data file.
    * \return config: `TransitionMatrix *` Pointer to object containing the
@@ -64,6 +67,10 @@ class TransitionMatrix {
   static TransitionMatrix *from_legacy(std::string file_name);
 
   /*! \brief Write the Transition Matrix to HDF5 binary output.
+   *
+   * This function takes care of the specific task of building a transition
+   * matrix memory data structure from a binary input file formatted according
+   * to the structure used by the original FORTRAN code.
    *
    * \param file_name: `string` Name of the binary configuration data file.
    */
@@ -79,8 +86,8 @@ class TransitionMatrix {
    *
    * \param _is: `int` Matrix type identifier
    * \param _lm: `int` Maximum field expansion order.
-   * \param _vk: `double`
-   * \param _exri: `double`
+   * \param _vk: `double` Wave number in scale units.
+   * \param _exri: `double` External medium refractive index.
    * \param _elements: `complex<double> *` Vectorized elements of the matrix.
    * \param _radius: `double` Radius for the single sphere case (defaults to 0.0).
    */
@@ -90,6 +97,9 @@ class TransitionMatrix {
   );
 
   /*! \brief Transition Matrix instance constructor for single sphere.
+   *
+   * This constructor allocates the memory structure needed to represent the transition
+   * matrix for the case of a single sphere.
    *
    * \param _lm: `int` Maximum field expansion order.
    * \param _vk: `double` Wave number in scale units.
@@ -104,11 +114,14 @@ class TransitionMatrix {
   );
 
   /*! \brief Transition Matrix instance constructor for a cluster of spheres.
+   *
+   * This constructor allocates the memory structure needed to represent the transition
+   * matrix for the case of a cluster of spheres.
    *
    * \param _nlemt: `int` Size of the matrix (2 * LE * (LE + 2)).
    * \param _lm: `int` Maximum field expansion order.
-   * \param _vk: `double`
-   * \param _exri: `double`
+   * \param _vk: `double` Wave number in scale units.
+   * \param _exri: `double` External medium refractive index.
    * \param _am0m: Matrix of complex.
    */
   TransitionMatrix(int _nlemt, int _lm, double _vk, double _exri, std::complex<double> **_am0m);
@@ -118,6 +131,14 @@ class TransitionMatrix {
   ~TransitionMatrix();
   
   /*! \brief Build transition matrix from binary input file.
+   *
+   * In some cases, it is necessary to perform calculations starting from a pre-computed
+   * transition matrix. If this matrix is not available in memory (e.g. because it was
+   * calculated by a different process), but it was saved in a binary file, this function
+   * can be used to load it back in memory. The function operates in two modes: "LEGACY",
+   * which reads the matrix data from a proprietary binary file, having the same structure
+   * as the one used by the original FORTRAN code, and "HDF5", which, instead, reads the
+   * data from an input file complying with the HDF5 format.
    *
    * \param file_name: `string` Name of the binary configuration data file.
    * \param mode: `string` Binary encoding. Can be one of ["LEGACY", "HDF5"]. Optional
@@ -128,6 +149,12 @@ class TransitionMatrix {
   static TransitionMatrix* from_binary(std::string file_name, std::string mode="LEGACY");
 
   /*! \brief Write the Transition Matrix to a binary file.
+   *
+   * This function writes a hard-copy of the transition matrix to an output file, making
+   * it available for subsequent processes to reload. The function operates in two modes:
+   * "LEGACY", which writes a proprietary binary file, using the same structure of the
+   * original FORTRAN code, and "HDF5", which, instead, writes the output to a file using
+   * the HDF5 format, thus leaving it available for inspection with external tools.
    *
    * \param file_name: `string` Name of the file to be written.
    * \param mode: `string` Binary encoding. Can be one of ["LEGACY", "HDF5"] . Optional