From 6c917608e81c8f708a82c73bfa2908720881ca72 Mon Sep 17 00:00:00 2001
From: Giovanni La Mura <giovanni.lamura@inaf.it>
Date: Mon, 25 Sep 2023 10:52:34 +0200
Subject: [PATCH] Adopt homogeneous doxygen format
---
src/sphere/List.h | 51 +++++++++++++++++++++++++-------------------
src/sphere/edfb.cpp | 52 +++++++++++++++++++++++----------------------
2 files changed, 56 insertions(+), 47 deletions(-)
diff --git a/src/sphere/List.h b/src/sphere/List.h
index d151b9ac..cb291134 100644
--- a/src/sphere/List.h
+++ b/src/sphere/List.h
@@ -1,3 +1,6 @@
+/*! \file List.h
+ */
+
#ifndef LIST_OUT_OF_BOUNDS_EXCEPTION
#define LIST_OUT_OF_BOUNDS_EXCEPTION 1
#endif
@@ -19,16 +22,18 @@
template<class T> class List {
protected:
int size; //!< Size of the List.
- struct element {T value; element* p_prev;}; //!< List element connector.
+ struct element {
+ T value; //!< Value of the list element.
+ element* p_prev; //!< Pointer to the previous element in the list.
+ }; //!< List element connector.
element *current, //!< Pointer to element affected by last operation.
*first, //!< Pointer to the first element in the List.
*last; //!< Pointer to the last element in the List.
public:
- /*! \fn List(int)
- * \brief List constructor.
+ /*! \brief List constructor.
*
- * Use the constructor List<T>(SIZE) to create a new list with a given
+ * Use the constructor List<T>([int length]) to create a new list with a given
* size. If the required size is not known in advance, it is recommended
* to create a List with SIZE=1 (this is the default behavior) and then
* to append the elements dynamically, using List.append(ELEMENT) (where
@@ -40,6 +45,8 @@ template<class T> class List {
* a = List<int>(1);
*
* b = List<int>();
+ *
+ * \param length: `int` The size of the list to be constructed [OPTIONAL, default=1].
*/
List(int length = 1) {
size = length;
@@ -65,8 +72,7 @@ template<class T> class List {
}
}
- /*! \fn append(T)
- * \brief Append an element at the end of the list.
+ /*! \brief Append an element at the end of the list.
*
* To dynamically create a list whose size is not known in advance,
* elements can be appended in an iterative way. Note that element
@@ -74,6 +80,8 @@ template<class T> class List {
* object. For this reason, after the List has been created, it is
* strongly advised to convert it to a C array by calling the function
* List.to_array().
+ *
+ * \param value: `T` The value of the element to be appended.
*/
void append(T value) {
element *p_prev = last;
@@ -84,14 +92,14 @@ template<class T> class List {
size++;
}
- /*! \fn get(int)
- * \brief Get the element at given index.
+ /*! \brief Get the element at given index.
*
* Get the element specified by the index argument. The first element
* has index 0 and the last one has index [size - 1].
*
- * \return T: the value of the element at the requested position.
- * \throw LIST_OUT_OF_BOUNDS_EXCEPTION: raised if the index is out of bounds.
+ * \param index: `int` The index of the element to be retrieved. 0 for first.
+ * \return value `T` The value of the element at the requested position.
+ * \throws LIST_OUT_OF_BOUNDS_EXCEPTION: Raised if the index is out of bounds.
*/
T get(int index) {
if (index < 0 || index > size - 1) {
@@ -102,24 +110,24 @@ template<class T> class List {
return current->value;
}
- /*! \fn length()
- * \brief Get the number of elements in the list.
+ /*! \brief Get the number of elements in the list.
*
* Get the number of elements currently stored in the list.
*
- * \return int: the size of the list.
+ * \return size `int` The size of the list.
*/
int length() {
return size;
}
- /*! \fn set(int, T)
- * \brief Set an element by index and value.
+ /*! \brief Set an element by index and value.
*
* Set the element at the position specified by the index to the value
* specified by the value argument.
*
- * \throw LIST_OUT_OF_BOUNDS_EXCEPTION: raised if the index is out of bounds.
+ * \param index: `int` The index of the element to be set. 0 for first.
+ * \param value: `int` The value to store in the pointed element.
+ * \throws LIST_OUT_OF_BOUNDS_EXCEPTION: Raised if the index is out of bounds.
*/
void set(int index, T value) {
if (index < 0 || index > size - 1) {
@@ -130,8 +138,7 @@ template<class T> class List {
current->value = value;
}
- /*! \fn to_array()
- * \brief Convert the list to a C array.
+ /*! \brief Convert the list to a C array.
*
* The List object is useful to dynamically manage a set of objects
* when the number of elements is not known in advance. However, the
@@ -142,15 +149,15 @@ template<class T> class List {
* a conversion from List to C array, returning a contiguous object,
* where indexed access can be used.
*
- * \return T[size]: a C array of type T and size equal to the List size.
+ * \return array `T*` A C array of type T and size equal to the List size.
*/
T* to_array() {
- T *result = new T[size];
+ T *array = new T[size];
current = last;
for (int i = size; i > 0; i--) {
- result[i - 1] = current->value;
+ array[i - 1] = current->value;
current = current->p_prev;
}
- return result;
+ return array;
}
};
diff --git a/src/sphere/edfb.cpp b/src/sphere/edfb.cpp
index 1f38c0a1..a40dea36 100644
--- a/src/sphere/edfb.cpp
+++ b/src/sphere/edfb.cpp
@@ -1,6 +1,4 @@
-/*! \brief C++ implementation of EDFB
- *
- * This code aims at replicating the original work-flow in C++.
+/*! \file edfb.cpp
*/
#include <cstdio>
@@ -13,8 +11,32 @@
using namespace std;
+/*! \brief Load a text file as a sequence of strings in memory.
+ *
+ * The configuration of the field expansion code in FORTRAN uses
+ * shared memory access and file I/O operations managed by different
+ * functions. Although this approach could be theoretically replicated,
+ * it is more convenient to handle input and output to distinct files
+ * using specific functions. load_file() helps in the task of handling
+ * input such as configuration files or text data structures that need
+ * to be loaded entirely. The function performs a line-by line scan of
+ * the input file and returns an array of strings that can be later
+ * parsed and ingested by the concerned code blocks. An optional pointer
+ * to integer allows the function to keep track of the number of file
+ * lines that were read, if needed.
+ *
+ * \param file_name: `string` The path of the file to be read.
+ * \param count: `int*` Pointer to an integer recording the number of
+ * read lines [OPTIONAL, default=NULL].
+ * \return array_lines `string*` An array of strings, one for each input
+ * file line.
+ */
string *load_file(string file_name, int *count);
+/*! \brief C++ implementation of EDFB
+ *
+ * This code aims at replicating the original work-flow in C++.
+ */
int main(int argc, char **argv) {
// Common variables set
complex<double> *dc0, ***dc0m;
@@ -23,13 +45,12 @@ int main(int argc, char **argv) {
double *xiv, *wns, *wls, *pus, *evs, *vss;
string vns[5];
- /// A helper variable to set the size of dc0m
- int max_nsh = 0;
+ int max_nsh = 0; // A helper variable to set the size of dc0m
int ici;
// Input file reading section
int num_lines = 0;
- int last_read_line; //!< Keep track of where INXI left the input stream
+ int last_read_line; // Keep track of where INXI left the input stream
string *file_lines = load_file("../../test_data/sphere/DEDFB", &num_lines);
// Configuration code
@@ -190,25 +211,6 @@ int main(int argc, char **argv) {
return 0;
}
-/*! \fn load_file(string, int*)
- * \brief Load a text file as a sequence of strings in memory.
- *
- * The configuration of the field expansion code in FORTRAN uses
- * shared memory access and file I/O operations managed by different
- * functions. Although this approach could be theoretically replicated,
- * it is more convenient to handle input and output to distinct files
- * using specific functions. load_file() helps in the task of handling
- * input such as configuration files or text data structures that need
- * to be loaded entirely. The function performs a line-byline scan of
- * the input file and returns an array of strings that can be later
- * parsed and ingested by the concerned code blocks. An optional pointer
- * to integer allows the function to keep track of the number of file
- * lines that were read, if needed.
- *
- * \param string file_name: The path of the file to be read.
- * \param [int *count = NULL]: Pointer to an integer recording the number of lines.
- * \return string*: An array of strings, one for each input file line.
- */
string *load_file(string file_name, int *count = 0) {
fstream input_file(file_name.c_str(), ios::in);
List<string> file_lines = List<string>();
--
GitLab