From e5ebe973bced1b1d7457baf09b8b3e0f07bf8e32 Mon Sep 17 00:00:00 2001
From: Giovanni La Mura <giovanni.lamura@inaf.it>
Date: Thu, 19 Oct 2023 11:21:21 +0200
Subject: [PATCH] Parse List docstrings according to doxygen syntax
---
src/include/List.h | 37 +++++++++++++++++++------------------
1 file changed, 19 insertions(+), 18 deletions(-)
diff --git a/src/include/List.h b/src/include/List.h
index 50c34130..c0f85992 100644
--- a/src/include/List.h
+++ b/src/include/List.h
@@ -8,15 +8,15 @@
#include <string>
/**
- * \brief Exception for out of bounds list requests.
+ * \brief Exception for out of bounds List requests.
*/
class ListOutOfBoundsException: public std::exception {
protected:
- //! \brief Minimum index defined in the list.
+ //! \brief Minimum index defined in the List.
int min_index;
- //! \brief Maximum index defined in the list.
+ //! \brief Maximum index defined in the List.
int max_index;
- //! \brief Index requested by user.
+ //! \brief List index requested by user.
int requested_index;
public:
@@ -58,7 +58,7 @@ public:
*
* For this reason, the best use of List objects is to collect all the
* desired members and then, once the element number is known, to convert
- * the List to C array, by calling List.to_array(). This function returns
+ * the List to C array, by calling `List.to_array()`. This function returns
* a contiguous array of type T[SIZE] that can be used for indexed access.
*/
template<class T> class List {
@@ -75,18 +75,19 @@ template<class T> class List {
public:
/*! \brief List constructor.
*
- * Use the constructor List<T>([int length]) 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
+ * to append the elements dynamically, using `List.append(ELEMENT)` (where
* ELEMENT needs to be a value of type T, corresponding to the class
* template specialization). Note that, due to the default behavior, the
* following calls are equivalent and they both produce an integer List
* with size equal to 1:
*
- * a = List<int>(1);
- *
- * b = List<int>();
+ * \code{.cpp}
+ * List<int> a = List<int>(1);
+ * List<int> b = List<int>();
+ * \endcode
*
* \param length: `int` The size of the list to be constructed [OPTIONAL, default=1].
*/
@@ -116,14 +117,14 @@ template<class T> class List {
}
}
- /*! \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
* manipulation is much more effective in a C array than in a 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().
+ * `List.to_array()`.
*
* \param value: `T` The value of the element to be appended.
*/
@@ -143,7 +144,7 @@ template<class T> class List {
*
* \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.
+ * \throws ListOutOfBoundsException: Raised if the index is out of bounds.
*/
T get(int index) {
if (index < 0 || index > size - 1) {
@@ -154,11 +155,11 @@ template<class T> class List {
return current->value;
}
- /*! \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.
+ * Get the number of elements currently stored in the List.
*
- * \return size `int` The size of the list.
+ * \return size `int` The size of the List.
*/
int length() {
return size;
@@ -171,7 +172,7 @@ template<class T> class List {
*
* \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.
+ * \throws ListOutOfBoundsException: Raised if the index is out of bounds.
*/
void set(int index, T value) {
if (index < 0 || index > size - 1) {
@@ -189,7 +190,7 @@ template<class T> class List {
* resulting object is not contiguosly stored in memory. As a result,
* access to specific elements in the middle of the list is not very
* effective, because the list needs to be walked every time up to
- * the desired position. In order to avoid this, List.to_array() makes
+ * the desired position. In order to avoid this, `List.to_array()` makes
* a conversion from List to C array, returning a contiguous object,
* where indexed access can be used.
*
--
GitLab