Skip to content

Commit 60ef27a

Browse files
degaudendegauden
committed
Rename headers and improve documentation across codebase
Renamed several header files for consistency and adjusted associated includes to reflect the changes. Enhanced code readability by adding detailed function, class, and template documentation, and standardized naming for constant functions in FloatPrecision.cpp.
1 parent 13ec695 commit 60ef27a

15 files changed

Lines changed: 140 additions & 43 deletions

File tree

ElementsExamples/ElementsExamples/functionExample.h renamed to ElementsExamples/ElementsExamples/FunctionExample.h

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/**
2-
* @file functionExample.h
2+
* @file FunctionExample.h
33
*
44
* @date Feb 16, 2016
55
* @author hubert
@@ -31,6 +31,12 @@
3131

3232
namespace Elements::Examples {
3333

34+
/**
35+
* Calculates the square of the given integer.
36+
*
37+
* @param j An integer to be squared.
38+
* @return The square of the input integer.
39+
*/
3440
ELEMENTS_API int functionExample(const int j);
3541

3642
} // namespace Elements::Examples

ElementsExamples/ElementsExamples/functionExample2.h renamed to ElementsExamples/ElementsExamples/FunctionExample2.h

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/**
2-
* @file functionExample.h
2+
* @file FunctionExample2.h
33
*
44
* @date Feb 16, 2016
55
* @author hubert
@@ -31,6 +31,14 @@
3131

3232
namespace Elements::Examples {
3333

34+
/**
35+
* @brief A simple function that returns the square of the input integer.
36+
*
37+
* This function takes an integer as input and returns the square of that integer.
38+
*
39+
* @param j The integer value to square.
40+
* @return The square of the input integer.
41+
*/
3442
ELEMENTS_API int functionExample2(const int j);
3543

3644
} // namespace Elements::Examples

‎ElementsExamples/ElementsExamples/SwigClassExample.h‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,15 +28,46 @@
2828

2929
namespace Elements::Examples {
3030

31+
/**
32+
* @class SwigClassExample
33+
*
34+
* @brief A class representing a simplified example for RA and DEC coordinates.
35+
*
36+
* This class provides access to RA (Right Ascension) and DEC (Declination) properties,
37+
* initialized through the constructor and accessible through getter methods.
38+
*/
3139
class ELEMENTS_API SwigClassExample final {
3240

3341
public:
42+
/**
43+
* @brief Constructs a SwigClassExample object with specified RA and DEC coordinates.
44+
*
45+
* This constructor initializes the RA (Right Ascension) and DEC (Declination) properties
46+
* with the provided values. If no values are provided, the default is 0.0 for both RA and DEC.
47+
*
48+
* @param ra The Right Ascension coordinate to initialize (default is 0.0).
49+
* @param dec The Declination coordinate to initialize (default is 0.0).
50+
*/
3451
explicit SwigClassExample(const double ra = 0.0, const double dec = 0.0) : m_ra(ra), m_dec(dec) {}
3552

36-
virtual ~SwigClassExample() = default;
53+
~SwigClassExample() = default;
3754

55+
/**
56+
* @brief Retrieves the Right Ascension (RA) value.
57+
*
58+
* This method returns the RA value stored in the instance of SwigClassExample.
59+
*
60+
* @return The RA (Right Ascension) value as a double.
61+
*/
3862
double getRa() const;
3963

64+
/**
65+
* @brief Retrieves the Declination (DEC) value of the object.
66+
*
67+
* This method provides access to the DEC property of the SwigClassExample instance.
68+
*
69+
* @return The DEC value as a double.
70+
*/
4071
double getDec() const;
4172

4273
private:

‎ElementsExamples/ElementsExamples/TemplateFunction.h‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,10 +31,18 @@
3131

3232
namespace Elements::Examples {
3333

34+
/**
35+
* @brief A template function that demonstrates the use of template functions.
36+
*
37+
* This function is a template function that can be instantiated with different types.
38+
* It is used to demonstrate the use of template functions in C++.
39+
*
40+
* @tparam T The type of the template function.
41+
*/
3442
template <typename T>
3543
ELEMENTS_API void templateFunction();
3644

37-
// template instance declaration
45+
/// Explicit instantiation of the template function for int and double
3846
extern template ELEMENTS_API void templateFunction<int>();
3947
extern template ELEMENTS_API void templateFunction<double>();
4048

‎ElementsExamples/ElementsExamples/Util.h‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,23 @@
2626
extern "C" {
2727
#endif
2828

29+
/**
30+
* @brief A function that performs a specific operation.
31+
*
32+
* This function returns an integer value. The operation performed by
33+
* the function is predefined and determined at implementation.
34+
*
35+
* @return An integer value representing the result of the operation.
36+
*/
2937
int myFunc(void);
3038

39+
/**
40+
* @brief A constant that defines a specific integral value.
41+
*
42+
* This constant is assigned the value 42 and is used throughout the program
43+
* to represent a fixed, predefined value. Its purpose may vary depending on
44+
* the context of use in different parts of the codebase.
45+
*/
3146
extern int MY_CONST;
3247

3348
#ifdef __cplusplus

‎ElementsExamples/python/ElementsExamples/PyBind11ProgramExample.py‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,8 @@
2626
from ElementsKernel import Logging
2727
from ElementsKernel import Exit
2828

29-
from testCallBack import test # pylint: disable=no-name-in-module,import-error
29+
# pylint: disable=no-name-in-module,import-error
30+
from testCallBack import test
3031

3132

3233
def norm(x):
@@ -53,8 +54,8 @@ def defineSpecificProgramOptions():
5354

5455
return parser
5556

56-
57-
def mainMethod(args): # pylint: disable=unused-argument
57+
# pylint: disable=unused-argument
58+
def mainMethod(args):
5859
""" The "main" method.
5960
This method is the entry point to the program. In this sense, it is similar to a main
6061
(and it is why it is called mainMethod()). The code below contains the calls to the

‎ElementsExamples/src/lib/default/functionExample.cpp‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
*
2020
*/
2121

22-
#include "ElementsExamples/functionExample.h"
22+
#include "ElementsExamples/FunctionExample.h"
2323

2424
namespace Elements::Examples {
2525

‎ElementsExamples/src/lib/other/functionExample2.cpp‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
*
2020
*/
2121

22-
#include "ElementsExamples/functionExample2.h"
22+
#include "ElementsExamples/FunctionExample2.h"
2323

2424
namespace Elements::Examples {
2525

‎ElementsExamples/src/program/ExtProgram.cpp‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,8 @@
2828
#include <boost/program_options.hpp> // for value, typed_value, options_description_easy_init, variable_value, bool_switch
2929

3030
#include "ElementsExamples/ClassExample.h" // for ClassExample
31+
#include "ElementsExamples/FunctionExample.h" // for functionExample
3132
#include "ElementsExamples/PrintProject.h" // for printProject
32-
#include "ElementsExamples/functionExample.h" // for functionExample
3333
#include "ElementsKernel/Exception.h" // for Exception
3434
#include "ElementsKernel/Main.h" // for MAIN_FOR
3535
#include "ElementsKernel/Module.h" // for Module

‎ElementsExamples/src/program/FloatPrecision.cpp‎

Lines changed: 27 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -64,77 +64,77 @@ void printTitle<long double>() {
6464
}
6565

6666
template <typename T>
67-
constexpr T Zero() {
67+
constexpr T zero() {
6868
return 0.0f;
6969
}
7070

7171
template <>
72-
constexpr double Zero<double>() {
72+
constexpr double zero<double>() {
7373
return 0.0;
7474
}
7575

7676
template <>
77-
constexpr long double Zero<long double>() {
77+
constexpr long double zero<long double>() {
7878
return 0.0l;
7979
}
8080

8181
template <typename T>
82-
constexpr T One() {
82+
constexpr T one() {
8383
return 1.0f;
8484
}
8585

8686
template <>
87-
constexpr double One<double>() {
87+
constexpr double one<double>() {
8888
return 1.0;
8989
}
9090

9191
template <>
92-
constexpr long double One<long double>() {
92+
constexpr long double one<long double>() {
9393
return 1.0l;
9494
}
9595

9696
template <typename T>
97-
constexpr T Two() {
97+
constexpr T two() {
9898
return 2.0f;
9999
}
100100

101101
template <>
102-
constexpr double Two<double>() {
102+
constexpr double two<double>() {
103103
return 2.0;
104104
}
105105

106106
template <>
107-
constexpr long double Two<long double>() {
107+
constexpr long double two<long double>() {
108108
return 2.0l;
109109
}
110110

111111
template <typename T>
112-
constexpr T Seven() {
112+
constexpr T seven() {
113113
return 7.0f;
114114
}
115115

116116
template <>
117-
constexpr double Seven<double>() {
117+
constexpr double seven<double>() {
118118
return 7.0;
119119
}
120120

121121
template <>
122-
constexpr long double Seven<long double>() {
122+
constexpr long double seven<long double>() {
123123
return 7.0l;
124124
}
125125

126126
template <typename T>
127-
constexpr T Ten() {
127+
constexpr T ten() {
128128
return 10.0f;
129129
}
130130

131131
template <>
132-
constexpr double Ten<double>() {
132+
constexpr double ten<double>() {
133133
return 10.0;
134134
}
135135

136136
template <>
137-
constexpr long double Ten<long double>() {
137+
constexpr long double ten<long double>() {
138138
return 10.0l;
139139
}
140140

@@ -151,24 +151,24 @@ void printFloatPrecision() {
151151

152152
printTitle<T>();
153153

154-
auto zero = Zero<T>();
155-
auto zero_plus = float_next(zero);
156-
auto next_after_zero = nextafter(zero, Two<T>());
157-
auto next_zero_toward = nexttoward(zero, Two<long double>());
154+
auto the_zero = zero<T>();
155+
auto zero_plus = float_next(the_zero);
156+
auto next_after_zero = nextafter(the_zero, two<T>());
157+
auto next_zero_toward = nexttoward(the_zero, two<long double>());
158158

159-
cout << "zero: " << zero << endl;
159+
cout << "zero: " << the_zero << endl;
160160
cout << "next to zero: " << zero_plus << endl;
161161
cout << "next after zero: " << next_after_zero << endl;
162162
cout << "next after zero toward two: " << next_zero_toward << endl;
163163

164-
auto one = One<T>();
165-
auto one_plus = float_next(one);
166-
auto next_after_one = nextafter(one, Two<T>());
167-
auto next_one_toward = nexttoward(one, Two<long double>());
168-
auto cos_pi_over_7 = cos(pi<T>() / Seven<T>());
169-
auto default_test_tolerance = pow(Ten<T>(), -numeric_limits<T>::digits10);
164+
auto the_one = one<T>();
165+
auto one_plus = float_next(the_one);
166+
auto next_after_one = nextafter(the_one, two<T>());
167+
auto next_one_toward = nexttoward(the_one, two<long double>());
168+
auto cos_pi_over_7 = cos(pi<T>() / seven<T>());
169+
auto default_test_tolerance = pow(ten<T>(), -numeric_limits<T>::digits10);
170170

171-
cout << "one: " << one << endl;
171+
cout << "one: " << the_one << endl;
172172
cout << "next to one: " << one_plus << endl;
173173
cout << "next after one: " << next_after_one << endl;
174174
cout << "next after one toward two: " << next_one_toward << endl;

0 commit comments

Comments
 (0)