Skip to content

Commit ad3215e

Browse files
mikee47mikee47
committed
Review and update code comments
1 parent 7964ccb commit ad3215e

11 files changed

+199
-66
lines changed

Diff for: ‎src/include/FlashString/Array.hpp

+25-18
Original file line numberDiff line numberDiff line change
@@ -25,33 +25,39 @@
2525
#include "ArrayPrinter.hpp"
2626

2727
/**
28-
* @brief Declare a global Array instance
28+
* @brief Declare a global Array& reference
29+
* @param name
30+
* @param ElementType
31+
* @note Use `DEFINE_FSTR_ARRAY` to instantiate the global Object
2932
*/
3033
#define DECLARE_FSTR_ARRAY(name, ElementType) extern const FSTR::Array<ElementType>& name;
3134

32-
/** @brief Define an array
33-
* @param name variable to identify the array
34-
* @param ElementType
35-
* @param elements
36-
* @note Unlike String, array is not nul-terminated
35+
/**
36+
* @brief Define an Array Object with global reference
37+
* @param name Name of Array& reference to define
38+
* @param ElementType
39+
* @param ... List of ElementType items
40+
* @note Unlike String, array is not NUL-terminated
3741
*/
3842
#define DEFINE_FSTR_ARRAY(name, ElementType, ...) \
3943
static DEFINE_FSTR_ARRAY_DATA(FSTR_DATA_NAME(name), ElementType, __VA_ARGS__); \
4044
DEFINE_FSTR_REF_NAMED(name, FSTR::Array<ElementType>);
4145

42-
/** @brief Define an array for local (static) use
43-
* @param name variable to identify the array
44-
* @param ElementType
45-
* @param elements
46+
/**
47+
* @brief Define an Array Object with local reference
48+
* @param name Name of Array& reference to define
49+
* @param ElementType
50+
* @param ... List of ElementType items
4651
*/
4752
#define DEFINE_FSTR_ARRAY_LOCAL(name, ElementType, ...) \
4853
static DEFINE_FSTR_ARRAY_DATA(FSTR_DATA_NAME(name), ElementType, __VA_ARGS__); \
4954
static constexpr DEFINE_FSTR_REF_NAMED(name, FSTR::Array<ElementType>);
5055

51-
/** @brief Define an array structure
52-
* @param name Name to use for data structure
53-
* @param ElementType
54-
* @param elements
56+
/**
57+
* @brief Define an Array data structure
58+
* @param name Name of data structure
59+
* @param ElementType
60+
* @param ... List of ElementType items
5561
*/
5662
#define DEFINE_FSTR_ARRAY_DATA(name, ElementType, ...) \
5763
constexpr const struct { \
@@ -81,9 +87,10 @@
8187
static DEFINE_FSTR_ARRAY_DATA(FSTR_DATA_NAME(name), ElementType, __VA_ARGS__); \
8288
LOAD_FSTR_ARRAY(name, FSTR_DATA_NAME(name).object)
8389

84-
/** @brief Define an Array containing data from an external file
85-
* @param name Name for the object
86-
* @param file Absolute path to the file containing the content
90+
/**
91+
* @brief Define an Array containing data from an external file
92+
* @param name Name for the object
93+
* @param file Absolute path to the file containing the content
8794
*/
8895
#define IMPORT_FSTR_ARRAY(name, ElementType, file) \
8996
IMPORT_FSTR_DATA(name, file) \
@@ -92,7 +99,7 @@
9299
namespace FSTR
93100
{
94101
/**
95-
* @brief describes an array of integral values stored in flash memory
102+
* @brief Class to access an array of integral values stored in flash
96103
*/
97104
template <typename ElementType> class Array : public Object<Array<ElementType>, ElementType>
98105
{

Diff for: ‎src/include/FlashString/ArrayPrinter.hpp

+4
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,10 @@
2323

2424
namespace FSTR
2525
{
26+
/**
27+
* @brief Class template to provide a simple way to print the contents of an array
28+
* @note Used by Array::printTo() method
29+
*/
2630
template <class ArrayType> class ArrayPrinter : public Printable
2731
{
2832
public:

Diff for: ‎src/include/FlashString/Map.hpp

+50-8
Original file line numberDiff line numberDiff line change
@@ -27,35 +27,69 @@
2727
#include "ObjectIterator.hpp"
2828

2929
/**
30-
* @brief Declare a Map
31-
* @tparam KeyType Integral type to use for key
32-
* @param name name of the map
30+
* @brief Declare a global Map& reference
31+
* @param name
32+
* @param KeyType Integral type to use for key
33+
* @param ContentType Object type to declare for content
3334
* @note Use `DEFINE_FSTR_MAP` to instantiate the global object
3435
*/
3536
#define DECLARE_FSTR_MAP(name, KeyType, ContentType) extern const FSTR::Map<KeyType, ContentType>& name;
3637

3738
/**
38-
* @brief Define a Map with reference
39+
* @brief Define a Map Object with global reference
40+
* @name Name of the Map& reference to define
41+
* @param KeyType Integral type to use for key
42+
* @param ContentType Object type to declare for content
43+
* @param ... List of MapPair definitions { key, &content }
44+
* @note Size will be calculated
3945
*/
4046
#define DEFINE_FSTR_MAP(name, KeyType, ContentType, ...) \
4147
static DEFINE_FSTR_MAP_DATA(FSTR_DATA_NAME(name), KeyType, ContentType, __VA_ARGS__); \
4248
DEFINE_FSTR_REF_NAMED(name, DECL((FSTR::Map<KeyType, ContentType>)));
4349

50+
/**
51+
* @brief Define a Map Object with local reference
52+
* @name Name of the Map& reference to define
53+
* @param KeyType Integral type to use for key
54+
* @param ContentType Object type to declare for content
55+
* @param ... List of MapPair definitions { key, &content }
56+
* @note Size will be calculated
57+
*/
4458
#define DEFINE_FSTR_MAP_LOCAL(name, KeyType, ContentType, ...) \
4559
static DEFINE_FSTR_MAP_DATA(FSTR_DATA_NAME(name), KeyType, ContentType, __VA_ARGS__); \
4660
static constexpr DEFINE_FSTR_REF_NAMED(name, DECL((FSTR::Map<KeyType, ContentType>)));
4761

62+
/**
63+
* @brief Define a Map Object with global reference, specifying the number of elements
64+
* @name Name of the Map& reference to define
65+
* @param KeyType Integral type to use for key
66+
* @param ContentType Object type to declare for content
67+
* @param size Number of elements
68+
* @param ... List of MapPair definitions { key, &content }
69+
*/
4870
#define DEFINE_FSTR_MAP_SIZED(name, KeyType, ContentType, size, ...) \
4971
static DEFINE_FSTR_MAP_DATA_SIZED(FSTR_DATA_NAME(name), KeyType, ContentType, size, __VA_ARGS__); \
5072
DEFINE_FSTR_REF_NAMED(name, DECL((FSTR::Map<KeyType, ContentType>)));
5173

74+
/**
75+
* @brief Define a Map Object with local reference, specifying the number of elements
76+
* @name Name of the Map& reference to define
77+
* @param KeyType Integral type to use for key
78+
* @param ContentType Object type to declare for content
79+
* @param size Number of elements
80+
* @param ... List of MapPair definitions { key, &content }
81+
*/
5282
#define DEFINE_FSTR_MAP_SIZED_LOCAL(name, KeyType, ContentType, size, ...) \
5383
static DEFINE_FSTR_MAP_DATA_SIZED(FSTR_DATA_NAME(name), KeyType, ContentType, size, __VA_ARGS__); \
5484
static constexpr DEFINE_FSTR_REF_NAMED(name, DECL((FSTR::Map<KeyType, ContentType>)));
5585

5686
/**
57-
* @brief Define a structure containing map data
58-
* @param name name of the map structure
87+
* @brief Define a Map data structure
88+
* @param name Name of data structure
89+
* @param KeyType Integral type to use for key
90+
* @param ContentType Object type to declare for content
91+
* @param ... List of MapPair definitions { key, &content }
92+
* @note Size will be calculated
5993
*/
6094
#define DEFINE_FSTR_MAP_DATA(name, KeyType, ContentType, ...) \
6195
DEFINE_FSTR_MAP_DATA_SIZED(name, KeyType, ContentType, \
@@ -64,8 +98,12 @@
6498
__VA_ARGS__)
6599

66100
/**
67-
* @brief Use in situations where the array size cannot be automatically calculated,
68-
* such as when combined with inline Strings via FS()
101+
* @brief Define a Map data structure, specifying the number of elements
102+
* @param name Name of data structure
103+
* @param KeyType Integral type to use for key
104+
* @param ContentType Object type to declare for content
105+
* @param size Number of elements
106+
* @param ... List of MapPair definitions { key, &content }
69107
*/
70108
#define DEFINE_FSTR_MAP_DATA_SIZED(name, KeyType, ContentType, size, ...) \
71109
constexpr const struct { \
@@ -101,6 +139,7 @@ class Map : public Object<Map<KeyType, ContentType>, Pair>
101139

102140
/**
103141
* @brief Lookup an integral key and return the index
142+
* @param key Key to locate, must be compatible with KeyType for equality comparison
104143
* @retval int If key isn't found, return -1
105144
*/
106145
template <typename TRefKey, typename T = KeyType>
@@ -119,6 +158,8 @@ class Map : public Object<Map<KeyType, ContentType>, Pair>
119158

120159
/**
121160
* @brief Lookup a String key and return the index
161+
* @param key
162+
* @param ignoreCase Whether search is case-sensitive (default: true)
122163
* @retval int If key isn't found, return -1
123164
*/
124165
template <typename TRefKey, typename T = KeyType>
@@ -142,6 +183,7 @@ class Map : public Object<Map<KeyType, ContentType>, Pair>
142183

143184
/**
144185
* @brief Lookup a key and return the entry, if found
186+
* @param key
145187
* @note Result validity can be checked using if()
146188
*/
147189
template <typename TRefKey> const Pair operator[](const TRefKey& key) const

Diff for: ‎src/include/FlashString/MapPrinter.hpp

+4
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,10 @@
2323

2424
namespace FSTR
2525
{
26+
/**
27+
* @brief Class template to provide a simple way to print the contents of a Map
28+
* @note Used by Map::printTo() method
29+
*/
2630
template <class MapType> class MapPrinter : public Printable
2731
{
2832
public:

Diff for: ‎src/include/FlashString/ObjectBase.hpp

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/**
2-
* ObjectBase.hpp - Definitions and macros common to all object types
2+
* ObjectBase.hpp - POD base class type for defining data structures
33
*
44
* Copyright 2019 mikee47 <[email protected]>
55
*
@@ -25,6 +25,10 @@
2525

2626
namespace FSTR
2727
{
28+
/**
29+
* @brief Used when defining data structures
30+
* @note Should not be used directly, use appropriate Object methods instead
31+
*/
2832
class ObjectBase
2933
{
3034
public:

Diff for: ‎src/include/FlashString/Print.hpp

+19-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/**
2-
* Print.cpp - Print support
2+
* Print.cpp - Helper function templates to simplify printing of objects and variables
33
*
44
* Copyright 2019 mikee47 <[email protected]>
55
*
@@ -23,17 +23,35 @@
2323

2424
namespace FSTR
2525
{
26+
/**
27+
* @brief Print an object
28+
* @param p
29+
* @param object
30+
* @retval size_t
31+
*/
2632
template <class ObjectType>
2733
typename std::enable_if<std::is_class<ObjectType>::value, size_t>::type print(Print& p, const ObjectType& object)
2834
{
2935
return object.printTo(p);
3036
}
3137

38+
/**
39+
* @brief Print an elementary variable
40+
* @param p
41+
* @param value
42+
* @retval size_t
43+
*/
3244
template <typename T> typename std::enable_if<!std::is_class<T>::value, size_t>::type print(Print& p, T value)
3345
{
3446
return p.print(value);
3547
}
3648

49+
/**
50+
* @brief Print an object or elementary variable appending a carriage return
51+
* @param p
52+
* @param value
53+
* @retval size_t
54+
*/
3755
template <typename T> size_t println(Print& p, T value)
3856
{
3957
size_t size = print(p, value);

0 commit comments

Comments
 (0)