Revise/simplify comments

Author: mikee47

object.rst

@@ -22,7 +22,7 @@ Macros follow the same pattern:
 
 ``DEFINE_FSTR_*``
    Creates a static data structure with an associated Object reference.
-   The _LOCAL variant makes the reference static.
+   The _LOCAL variant makes the reference ``static constexpr``.
 
 ``DECLARE_FSTR_*``
    Use this in a header to declare Object reference so it can be used across

src/include/FlashString/Array.hpp

@@ -50,10 +50,7 @@
 	DEFINE_FSTR_REF_NAMED(name, FSTR::Array<ElementType>);
 
 /**
- * @brief Define an Array Object with local reference
- * @param name Name of Array& reference to define
- * @param ElementType
- * @param ... List of ElementType items
+ * @brief Like DEFINE_FSTR_ARRAY except reference is declared static constexpr
  */
 #define DEFINE_FSTR_ARRAY_LOCAL(name, ElementType, ...)                                                                \
 	static DEFINE_FSTR_ARRAY_DATA(FSTR_DATA_NAME(name), ElementType, __VA_ARGS__);                                     \
@@ -98,12 +95,14 @@
  * @param name Name for the Array object
  * @param ElementType Array element type
  * @param file Absolute path to the file containing the content
- * @See See also `IMPORT_FSTR_DATA`
- * @{
+ * @see See also `IMPORT_FSTR_DATA`
  */
 #define IMPORT_FSTR_ARRAY(name, ElementType, file) IMPORT_FSTR_OBJECT(name, FSTR::Array<ElementType>, file)
+
+/**
+ * @brief Like IMPORT_FSTR_ARRAY except reference is declared static constexpr
+ */
 #define IMPORT_FSTR_ARRAY_LOCAL(name, ElementType, file) IMPORT_FSTR_OBJECT_LOCAL(name, FSTR::Array<ElementType>, file)
-/** @} */
 
 namespace FSTR
 {

src/include/FlashString/Map.hpp

@@ -54,12 +54,7 @@
 	DEFINE_FSTR_REF_NAMED(name, DECL((FSTR::Map<KeyType, ContentType>)));
 
 /**
- * @brief Define a Map Object with local reference
- * @name Name of the Map& reference to define
- * @param KeyType Integral type to use for key
- * @param ContentType Object type to declare for content
- * @param ... List of MapPair definitions { key, &content }
- * @note Size will be calculated
+ * @brief Like DEFINE_FSTR_MAP except reference is declared static constexpr
  */
 #define DEFINE_FSTR_MAP_LOCAL(name, KeyType, ContentType, ...)                                                         \
 	static DEFINE_FSTR_MAP_DATA(FSTR_DATA_NAME(name), KeyType, ContentType, __VA_ARGS__);                              \
@@ -78,12 +73,7 @@
 	DEFINE_FSTR_REF_NAMED(name, DECL((FSTR::Map<KeyType, ContentType>)));
 
 /**
- * @brief Define a Map Object with local reference, specifying the number of elements
- * @name Name of the Map& reference to define
- * @param KeyType Integral type to use for key
- * @param ContentType Object type to declare for content
- * @param size Number of elements
- * @param ... List of MapPair definitions { key, &content }
+ * @brief Like DEFINE_FSTR_MAP_SIZED except reference is declared static
  */
 #define DEFINE_FSTR_MAP_SIZED_LOCAL(name, KeyType, ContentType, size, ...)                                             \
 	static DEFINE_FSTR_MAP_DATA_SIZED(FSTR_DATA_NAME(name), KeyType, ContentType, size, __VA_ARGS__);                  \

src/include/FlashString/Object.hpp

@@ -93,20 +93,21 @@
  * @param name Name for the object
  * @param ObjectType Object type for reference
  * @param file Absolute path to the file containing the content
- * @See See also `IMPORT_FSTR_DATA`
+ * @see See also `IMPORT_FSTR_DATA`
  * @note Can only be used at file scope
- * @{
  */
 #define IMPORT_FSTR_OBJECT(name, ObjectType, file)                                                                     \
 	IMPORT_FSTR_DATA(FSTR_DATA_NAME(name), file)                                                                       \
 	extern "C" const FSTR::ObjectBase FSTR_DATA_NAME(name);                                                            \
 	DEFINE_FSTR_REF(name, ObjectType, FSTR_DATA_NAME(name));
 
+/**
+ * @brief Like IMPORT_FSTR_OBJECT except reference is declared static constexpr
+ */
 #define IMPORT_FSTR_OBJECT_LOCAL(name, ObjectType, file)                                                               \
 	IMPORT_FSTR_DATA(FSTR_DATA_NAME(name), file)                                                                       \
 	extern "C" const FSTR::ObjectBase FSTR_DATA_NAME(name);                                                            \
 	static constexpr DEFINE_FSTR_REF(name, ObjectType, FSTR_DATA_NAME(name));
-/** @} */
 
 namespace FSTR
 {

src/include/FlashString/String.hpp

@@ -79,9 +79,7 @@ typedef const __FlashStringHelper* flash_string_t;
 	DEFINE_FSTR_REF_NAMED(name, FSTR::String);
 
 /**
- * @brief Define a FSTR::String object with local reference
- * @param name Name of FSTR::String& reference to define
- * @param str Content of the FSTR::String
+ * @brief Like DEFINE_FSTR except reference is declared static constexpr
  */
 #define DEFINE_FSTR_LOCAL(name, str)                                                                                   \
 	static DEFINE_FSTR_DATA(FSTR_DATA_NAME(name), str);                                                                \
@@ -130,12 +128,14 @@ typedef const __FlashStringHelper* flash_string_t;
  * @brief Define a FSTR::String containing data from an external file
  * @param name Name for the FSTR::String object
  * @param file Absolute path to the file containing the content
- * @See See also `IMPORT_FSTR_DATA`
- * @{
+ * @see See also `IMPORT_FSTR_DATA`
  */
 #define IMPORT_FSTR(name, file) IMPORT_FSTR_OBJECT(name, FSTR::String, file)
+
+/**
+ * @brief Like IMPORT_FSTR except reference is declared static constexpr
+ */
 #define IMPORT_FSTR_LOCAL(name, file) IMPORT_FSTR_OBJECT_LOCAL(name, FSTR::String, file)
-/** @} */
 
 /**
  * @brief declare a table of FlashStrings

src/include/FlashString/Vector.hpp

@@ -50,11 +50,7 @@
 	DEFINE_FSTR_REF_NAMED(name, FSTR::Vector<ObjectType>);
 
 /**
- * @brief Define a Vector Object with local reference
- * @param name Name of Vector& reference to define
- * @param ObjectType
- * @param ... List of ObjectType* pointers
- * @note Size will be calculated
+ * @brief Like DEFINE_FSTR_VECTOR except reference is declared static constexpr
  */
 #define DEFINE_FSTR_VECTOR_LOCAL(name, ObjectType, ...)                                                                \
 	static DEFINE_FSTR_VECTOR_DATA(FSTR_DATA_NAME(name), ObjectType, __VA_ARGS__);                                     \
@@ -73,12 +69,7 @@
 	DEFINE_FSTR_REF_NAMED(name, FSTR::Vector<ObjectType>);
 
 /**
- * @brief Define a Vector Object with local reference, specifying the number of elements
- * @param name Name of Vector& reference to define
- * @param ObjectType
- * @param size Number of elements
- * @param ... List of ObjectType* pointers
- * @note Use in situations where the array size cannot be automatically calculated
+ * @brief Like DEFINE_FSTR_VECTOR_SIZED except reference is declared static constexpr
  */
 #define DEFINE_FSTR_VECTOR_SIZED_LOCAL(name, ObjectType, size, ...)                                                    \
 	static DEFINE_FSTR_VECTOR_DATA_SIZED(FSTR_DATA_NAME(name), ObjectType, size, __VA_ARGS__);                         \