Revise documentation with doxygen information

Move into groups and add API information section to pages

Author: mikee47

README.rst

@@ -1,5 +1,5 @@
-FlashString Library
-===================
+FlashString
+===========
 
 .. highlight:: C++
 
@@ -15,7 +15,7 @@ but could be ported to other platforms relatively easily.
 Perhaps the most common use for PROGMEM data is passing strings around, usually as a
 pointer to a 'C' NUL-terminated char array. There are a couple of problems with this:
 
-1. If we need to know how long the string is, we need to call *strlen_P*, which is
+1. If we need to know how long the string is, we need to call :c:func:`strlen_P`, which is
    *really* expensive computationally.
 2. We can't include NUL characters in the string.
 
@@ -26,37 +26,41 @@ Both of these are easily solved by passing the length along with the string, lik
 
 Of course, passing two parameters instead of one gets tiresome and is not very C++, is it?
 
-
-The library
------------
-
 This library implements C++ objects stored in flash memory, using macros to create the
 data structures. The object interfaces are implemented using class templates for
 performance and flexibility.
 
 The classes are all in the ``FSTR`` namespace.
 
-The Sming framework provides several aliases to provide compatibility with existing code:
-
--  ``FlashString`` -> ``FSTR::String``
--  ``FlashMemoryStream`` -> ``FSTR::Stream``
--  ``TemplateFlashMemoryStream`` -> ``FSTR::TemplateStream``
-
-Only ``FlashString`` is provided by default as it integrates with Wiring Strings.
-If you wish to use any of the other object types, #include the appropriate header::
-
-   #include <FlashString/Array.hpp>
-
-You can find more detail in the following sections.
-
 .. toctree::
-
+   :maxdepth: 1
+   
    object
    string
    array
+   table
    vector
    map
+   streams
    utility
+
+
+Sming Integration
+-----------------
+
+Sming provides several aliases to provide compatibility with existing code:
+
+-  :cpp:type:`FlashString` -> :cpp:class:`FSTR::String`
+-  :cpp:class:`FlashMemoryStream` -> :cpp:class:`FSTR::Stream`
+-  :cpp:class:`TemplateFlashMemoryStream` -> :cpp:class:`FSTR::TemplateStream`
+
+
+Other pages
+-----------
+
+.. toctree::
+   :maxdepth: 1
+   
    upgrade
    changelog
    technical

about.rst

@@ -13,32 +13,32 @@ I created it as a one-file solution to address these specific issues:
    FlashString classes as if they were just stored in flash so I wouldn't have to wrap
    everything in a macro, like F() does.
 
-   Solution: The FlashString class.
+   Solution: The :cpp:class:`FlashString` class.
 
 2. Using PROGMEM directly for data is cumbersome, slow and fraught with danger: It's inherently unsafe
    because of the alignment issues. Some smart cookie came up with a compiler patch so it could
    insert the correct instructions and thus avoid alignment exceptions. However, that still causes
    execution of inefficient code since the hardware requires we perform aligned accesses.
    Generating the structures correctly in the first place felt the best way forward.
 
-   Solution: DEFINE_FSTR
+   Solution: :c:func:`DEFINE_FSTR`
 
 3. Sharing flash data structures globally
 
-   Solution: DECLARE_FSTR
+   Solution: :c:func:`DECLARE_FSTR`
 
 4. How to get content into PROGMEM without having to manually convert everything into
    C structures. One solution to this is using external tools but that complicates the build
    process and felt un-necessary.
 
-   Solution: IMPORT_FSTR
+   Solution: :c:func:`IMPORT_FSTR`
 
 5. Relying on SPIFFS for serving fixed content is inefficient and problematic if/when the
    filesystem gets corrupted. I needed a solution which allowed large content to be
    served up without requiring a filesystem. The long term solution to this is, of course,
    a read-only filesystem but that is a complex thing indeed to do properly.
 
-   Solution: FlashMemoryStream
+   Solution: :cpp:class:`FlashMemoryStream`
 
 
 Embedded microsystems

array.rst

@@ -8,7 +8,7 @@ Introduction
 
 Supports arrays of simple types, such as char, int, double, or POD structures (i.e. basic C structures).
 
-The ``Array`` is a class template, so requires an additional ``ElementType`` parameter::
+:cpp:class:`FSTR::Array` is a class template, so requires an additional ``ElementType`` parameter::
 
    #include <FlashString/Array.hpp>
 
@@ -39,45 +39,13 @@ You can share Arrays between translation units by declaring it in a header::
    DECLARE_FSTR_ARRAY(table);
 
 
-Tables
+Macros
 ------
 
-Simple tables can be implemented using Arrays, like this::
-
-   struct TableRow {
-      float columns[3];
-      
-      int operator[](size_t index) const
-      {
-         return columns[index];
-      } 
-   };
-   DEFINE_FSTR_ARRAY(table, TableRow,
-      {0.1, 0.2, 0.3},
-      {0.6, 0.7, 0.8}
-   );
-   for(auto row: table) {
-      Serial.printf("%f, %f, %f\n", row[0], row[1], row[2]);
-   }
-
-Each row is a fixed size. The ``TableRow`` class template is provided to simplify this::
-
-   #include <FlashString/Table.hpp>
-
-   using FloatRow = FSTR::TableRow<float, 3>;
-   DEFINE_FSTR_ARRAY(table, FloatRow,
-      {0.1, 0.2, 0.3},
-      {0.6, 0.7, 0.8}
-   );
-   table.printTo(Serial);
-   table.println();
-
-
-If you want to create a table with rows of different sizes or types, use a :doc:`Vector <vector>`.
-
+.. doxygengroup:: fstr_array
+   :content-only:
 
-Additional Macros
------------------
+Classes
+-------
 
-DEFINE_FSTR_ARRAY_DATA(name, ...)
-   Define the data structure without an associated reference.
+.. doxygenclass:: FSTR::Array

component.mk

@@ -1,2 +1,7 @@
 COMPONENT_INCDIRS := src/include
 COMPONENT_SRCDIRS := src
+COMPONENT_DOXYGEN_INPUT := src/include
+COMPONENT_DOXYGEN_INCLUDE_PATH := src/include/config.hpp
+COMPONENT_DOXYGEN_PREDEFINED := \
+	FSTR_INLINE= \
+	FSTR_PACKED=

map.rst

@@ -1,15 +1,15 @@
-Associative Maps
-================
+Maps
+====
 
 .. highlight:: C++
 
 Introduction
 ------------
 
-A ``Map`` is analogous to the Wiring HashMap class, allowing content to be indexed using
+A :cpp:class:`FSTR::Map` is analogous to the Wiring :cpp:class:`HashMap` class, allowing content to be indexed using
 a key value.
 
-The Map contains an array of ``MapPair`` structures::
+The Map contains an array of :cpp:class:`FSTR::MapPair` structures::
 
    struct MapPair<KeyType, ContentType> {
       KeyType key_;
@@ -22,8 +22,10 @@ It may also be a ``String`` Object (or, more precisely, ``String*``).
 ``ContentType`` can be any Object type (String, Array, Vector or Map).
 This allows hierarchical structures to be created.
 
-Example: int => String
-----------------------
+.. |rArr| unicode:: 0x21D2 .. => arrow
+
+Example: int |rArr| String
+--------------------------
 
 Here's a basic example using integer keys::
 
@@ -51,8 +53,8 @@ We can now do this::
    }
 
 
-Example: String => String
--------------------------
+Example: String |rArr| String
+-----------------------------
 
 Both the key and the content are stored as Strings::
 
@@ -111,9 +113,16 @@ Note: ``FSTR::`` namespace qualifier omitted for clarity.
 Usually, each MapPair is 8 bytes, but if the key is a double or int64 it would be 12 bytes.
 
 
-Additional Macros
------------------
+Macros
+------
+
+.. doxygengroup:: fstr_map
+   :content-only:
+
+
+Class Templates
+---------------
 
-DEFINE_FSTR_MAP_DATA(name, KeyType, ContentType, ...)
-   Define the map structure without an associated reference.
+.. doxygenclass:: FSTR::Map
 
+.. doxygenclass:: FSTR::MapPair

object.rst

@@ -6,25 +6,25 @@ Objects
 Introduction
 ------------
 
-An ``Object`` is a class template with array-like behaviour, though it is not used directly.
+An :cpp:class:`FSTR::Object` is a class template with array-like behaviour, though it is not used directly.
 
 Instead, use one of the four classes in the library:
 
--  String
--  Array
--  Vector
--  Map
+-  :doc:`String <string>`
+-  :doc:`Array <array>`
+-  :doc:`Vector <vector>`
+-  :doc:`Map <map>`
 
 Each type has its own set of macros for easy data construction, and creation of the
 appropriate Object class which may then be used directly.
 
 Macros follow the same pattern:
 
-DEFINE_FSTR_\*
+``DEFINE_FSTR_*``
    Creates a static data structure with an associated Object reference.
    The _LOCAL variant makes the reference static.
 
-DECLARE_FSTR_\*
+``DECLARE_FSTR_*``
    Use this in a header to declare Object reference so it can be used across
    translation units.
 
@@ -34,10 +34,10 @@ Created symbols are C++ and adopt any enclosing namespaced.
 Reading Object content
 ----------------------
 
-To read parts of an Object, use the ``read()`` method.
+To read parts of an Object, use the :cpp:func:`FSTR::Object::read` method.
 
-If the data isn't used very often, use the ``readFlash()`` method instead as it avoids
-disrupting the cache. The ``Stream`` class (alias FlashMemoryStream) does this by default.
+If the data isn't used very often, use the :cpp:func:`FSTR::Object::readFlash` method instead as it avoids
+disrupting the cache. The :cpp:class:`FSTR::Stream` class (alias :cpp:class:`FlashMemoryStream`) does this by default.
 
 
 Object Internals
@@ -46,7 +46,7 @@ Object Internals
 This section provides some examples of how structures are created, but in normal use you
 should use the provided macros as they simplify the task and include structure validity checks.
 
-``ObjectBase`` is a non-template
+:cpp:class:`FSTR::ObjectBase` is a non-template
 `POD <https://stackoverflow.com/questions/4178175/what-are-aggregates-and-pods-and-how-why-are-they-special/7189821>`__
 base class, and looks like this (methods omitted)::
 
@@ -80,8 +80,8 @@ If you want to access it as an array, do this::
 References are an efficient and convenient way to access an Object, and should not consume
 any memory themselves as the compiler/linker resolve them to the actual object.
 
-However, in practice the Espressif compiler stores a full pointer to most things and if
-the references aren't declared PROGMEM they'll consume RAM.
+However, in practice the Espressif compiler stores a full pointer to most things to support
+relative addressing, and if the references aren't declared PROGMEM they'll consume RAM.
 
 
 Copy behaviour
@@ -123,14 +123,16 @@ This means classes cannot have:
 -  virtual functions
 -  base classes (until C++17)
 
-This is why ObjectBase is used for data structures.
-We work using an ``Object`` class template as it provides the necessary constructors::
+This is why :cpp:class:`FSTR::ObjectBase` is used to define data structures.
+
+Classes created using the :cpp:class:`FSTR::Object` template ensures the necessary constructors
+are available to do this::
 
    auto myCopy = flashHelloData.object.as<FSTR::String>();
    Serial.print("myCopy.length() = ");
    Serial.println(myCopy.length());
 
-The macros create an appropriate Object reference for you.
+The macros create an appropriate Object& reference for you.
 
 
 Structure checks
@@ -150,4 +152,15 @@ Most compilers are quite relaxed about this but ``GCC 4.8.5`` is particularly th
 In testing, this happens with references for global Objects, which of course cannot be constexpr.
 To fix it, the offending Object either needs to be redefined LOCAL, or if the Object data is in
 scope (i.e. defined in the same source file) then you can get a direct pointer to it using
-the ``FSTR_PTR`` macro.
+the :c:func:`FSTR_PTR` macro.
+
+Macros
+------
+
+.. doxygengroup:: fstr_object
+   :content-only:
+
+Class Template
+--------------
+
+.. doxygenclass:: FSTR::Object

src/include/FlashString/Array.hpp

@@ -1,4 +1,4 @@
-/**
+/****
  * Array.hpp - Defines the Array class and associated macros
  *
  * Copyright 2019 mikee47 <[email protected]>
@@ -24,6 +24,12 @@
 #include "Object.hpp"
 #include "ArrayPrinter.hpp"
 
+/**
+ * @defgroup fstr_array Arrays
+ * @ingroup FlashString
+ * @{
+ */
+
 /**
  * @brief Declare a global Array& reference
  * @param name
@@ -90,6 +96,7 @@
 /**
  * @brief Define an Array containing data from an external file
  * @param name Name for the object
+ * @param ElementType
  * @param file Absolute path to the file containing the content
  */
 #define IMPORT_FSTR_ARRAY(name, ElementType, file)                                                                     \
@@ -100,6 +107,7 @@ namespace FSTR
 {
 /**
  * @brief Class to access an array of integral values stored in flash
+ * @tparam ElementType
  */
 template <typename ElementType> class Array : public Object<Array<ElementType>, ElementType>
 {
@@ -122,3 +130,5 @@ template <typename ElementType> class Array : public Object<Array<ElementType>,
 };
 
 } // namespace FSTR
+
+/** @} */

src/include/FlashString/ArrayPrinter.hpp

@@ -1,4 +1,4 @@
-/**
+/****
  * ArrayPrinter.cpp - Print support for arrays
  *
  * Copyright 2019 mikee47 <[email protected]>