Documentation fixes

Sming/Arch/Esp32/Components/esp_idf/README.rst

@@ -0,0 +1,4 @@
+ESP IDF
+=======
+
+Provides make targets which are redirected to the ESP IDF.

Sming/Arch/Esp32/Components/esp_spiffs/README.rst

@@ -0,0 +1,4 @@
+Esp32 SPIFFS
+============
+
+SPIFFS implementation for ESP32 devices.

Sming/Arch/Esp8266/Components/driver/gpio.rst

@@ -5,3 +5,4 @@ SDK definitions for GPIO.
 
 .. doxygengroup:: gpio_driver
    :content-only:
+   :members:

Sming/Arch/Esp8266/Components/driver/hw_timer.rst

@@ -27,3 +27,4 @@ API Documentation
 
 .. doxygengroup:: hw_timer
    :content-only:
+   :members:

Sming/Arch/Esp8266/Components/driver/i2s.rst

@@ -62,3 +62,4 @@ API Documentation
 
 .. doxygengroup:: i2s_driver
    :content-only:
+   :members:

Sming/Arch/Esp8266/Components/driver/os_timer.rst

@@ -3,3 +3,4 @@ OS Timer
 
 .. doxygengroup:: os_timer
    :content-only:
+   :members:

Sming/Arch/Esp8266/Components/driver/pwm.rst

@@ -19,3 +19,4 @@ API Documentation
 
 .. doxygengroup:: pwm_driver
    :content-only:
+   :members:

Sming/Arch/Esp8266/Components/driver/uart.rst

@@ -5,3 +5,4 @@ Custom asynchronous driver.
 
 .. doxygengroup:: uart_driver
    :content-only:
+   :members:

Sming/Arch/Esp8266/Components/spi_flash/api.rst

@@ -3,3 +3,4 @@ API Documentation
 
 .. doxygengroup:: spi_flash
    :content-only:
+   :members:

Sming/Arch/Esp8266/Components/spi_flash/precache.rst

@@ -49,3 +49,4 @@ API Documentation
 
 .. doxygengroup:: iram_precache
    :content-only:
+   :members:

Sming/Arch/Host/Components/driver/gpio.rst

@@ -9,3 +9,4 @@ API Documentation
 -----------------
 
 .. doxygenclass:: DigitalHooks
+   :members:

Sming/Components/rboot/include/Data/Stream/RbootOutputStream.h

@@ -18,6 +18,9 @@
 #include <Data/Stream/ReadWriteStream.h>
 #include <rboot-api.h>
 
+/**
+ * @brief Write-only stream type used during rBoot firmware updates
+ */
 class RbootOutputStream : public ReadWriteStream
 {
 public:

Sming/Components/ssl/adapter.rst

@@ -1,16 +1,31 @@
-Adapter API
-===========
+SSL Adapter API
+===============
 
 These classes provide the interface between a :cpp:class:`Ssl::Session` and an appropriate adapter.
 
- *
- * Returned `int` error codes are 0 for success, or < 0 for error.
- *
- * The error codes themselves are implementation-specific.
- * Use `getErrorString()` to obtain the message.
- * SSL `Alerts` are also reported via error codes. Use `getAlert` 
 
+Error codes
+-----------
+
+Error codes are implementation specific, however 0 always indicates success and < 0 for error.
+
+To obtain a description for an error code, use :cpp:func:`Ssl::Connection::getErrorString`.
+
+SSL `Alerts` are reported via error codes. To obtain the alert code call
+:cpp:func:`Ssl::Connection::getAlert` which returns an :cpp:enum:`Ssl::Alert` code.
+If the error code is not an alert then ``Alert::INVALID`` is returned.
+
+.. doxygenenum:: Ssl::Alert
+
+
+Classes
+-------
 
 .. doxygenclass:: Ssl::Factory
+   :members:
+
 .. doxygenclass:: Ssl::Context
+   :members:
+
 .. doxygenclass:: Ssl::Connection
+   :members:

Sming/Components/ssl/include/Network/Ssl/Alert.h

@@ -44,9 +44,10 @@ namespace Ssl
 
 /**
  * @brief Alert codes defined by the standard
+ * @see See https://tools.ietf.org/html/rfc8446#page-85
  */
 enum class Alert {
-	Invalid = -1,
+	Invalid = -1, ///< Not an alert code
 #define XX(tag, code) tag = code,
 	SSL_ALERT_CODE_MAP(XX)
 #undef XX

Sming/Components/ssl/session.rst

@@ -2,6 +2,12 @@ Session
 =======
 
 .. doxygenclass:: Ssl::Session
+   :members:
+
 .. doxygenclass:: Ssl::SessionId
+   :members:
+
 .. doxygenstruct:: Ssl::Options
+   :members:
+
 .. doxygenenum:: MaxBufferSize

Sming/Components/ssl/upgrade.rst

@@ -111,7 +111,8 @@ has access to the current SSL session and HTTP request and can modify them accor
      // We're using validators, so don't attempt to validate full certificate
      session.options.verifyLater = true;
 
-     session.fragmentSize = Ssl::eSEFS_16K;
+     // Go with maximum buffer sizes
+     session.maxBufferSize = Ssl::MaxBufferSize::K16;
    }
 
 Note also that the ``Fingerprints`` class has been removed.
@@ -130,8 +131,8 @@ organised within the ``Crypto`` namespace.
 
 This is primarily for use with the SSL interface but does not require SSL to be enabled.
 
-The cryptographic 'C' libraries themselves may be used directly by your application, regardless
-of which SSL adapter is in use, or even if SSL is disabled.
+Alternatively, the cryptographic 'C' libraries themselves may be used directly by your application,
+regardless of which SSL adapter is in use, or even if SSL is disabled.
 
 For example the following old code is using axTLS cryptographic functions::
 

Sming/Core/Data/Stream/Base64OutputStream.h

@@ -16,12 +16,9 @@
 #include "libb64/cencode.h"
 
 /**
- * @brief      Base64 Stream
- * @ingroup    stream data
- *
- *  @{
+ * @brief    Read-only stream to emit base64-encoded content from source stream
+ * @ingroup stream data
 */
-
 class Base64OutputStream : public StreamTransformer
 {
 public:
@@ -48,5 +45,3 @@ class Base64OutputStream : public StreamTransformer
 	base64_encodestate state = {};
 	base64_encodestate lastState = {};
 };
-
-/** @} */

Sming/Core/Data/Stream/ChunkedStream.h

@@ -15,12 +15,12 @@
 #include "../StreamTransformer.h"
 
 /**
- * @brief      Data chunked stream class
- * @ingroup    stream data
+ * @brief Read-only stream to obtain data using HTTP chunked encoding
  *
- *  @{
-*/
-
+ * Used where total length of stream is not known in advance
+ *
+ * @ingroup  stream data
+ */
 class ChunkedStream : public StreamTransformer
 {
 public:
@@ -29,5 +29,3 @@ class ChunkedStream : public StreamTransformer
 protected:
 	size_t transform(const uint8_t* source, size_t sourceLength, uint8_t* target, size_t targetLength) override;
 };
-
-/** @} */

Sming/Core/Data/Stream/DataSourceStream.h

@@ -15,9 +15,12 @@
 #include "WString.h"
 #include <unistd.h>
 
+/** @defgroup   stream Stream functions
+ *  @brief      Data stream classes
+*/
+
 /** @brief  Data stream type
  *  @ingroup constants
- *  @{
  */
 enum StreamType {
 	eSST_Invalid,	///< Stream content not valid
@@ -28,14 +31,11 @@ enum StreamType {
 	eSST_User,		 ///< User defined data stream
 	eSST_Unknown	 ///< Unknown data stream type
 };
-/** @} */
-
-/** @defgroup   stream Stream functions
- *  @brief      Data stream classes
- *  @{
-*/
 
-///Base class for data source stream
+/**
+ * @brief Base class for read-only stream
+ * @ingroup stream
+ */
 class IDataSourceStream : public Stream
 {
 public:
@@ -165,5 +165,3 @@ class IDataSourceStream : public Stream
 	 */
 	String readString(size_t maxLen = UINT16_MAX);
 };
-
-/** @} */

Sming/Core/Data/Stream/EndlessMemoryStream.h

@@ -12,17 +12,14 @@
 
 #include "MemoryDataStream.h"
 
-/** @addtogroup stream
- *  @{
- */
-
 /**
  * @brief Memory stream that stores unlimited number of bytes.
  *
- * @note Memory is allocated on write and released when all written
+ * Memory is allocated on write and released when all written
  * bytes have been read out. This behaviour differs from a circular buffer
  * as the size is not fixed.
  *
+ * @ingroup stream
  */
 class EndlessMemoryStream : public ReadWriteStream
 {
@@ -59,5 +56,3 @@ class EndlessMemoryStream : public ReadWriteStream
 private:
 	MemoryDataStream* stream = nullptr;
 };
-
-/** @} */

Sming/Core/Data/Stream/FileStream.h

@@ -14,12 +14,9 @@
 #include "FileSystem.h"
 
 /**
-  * @brief      File stream class
-  * @ingroup    stream data
-  *
-  *  @{
+ * @brief    File stream class
+ * @ingroup  stream data
  */
-
 class FileStream : public ReadWriteStream
 {
 public:
@@ -175,5 +172,3 @@ class FileStream : public ReadWriteStream
 	size_t size = 0;
 	int lastError = SPIFFS_OK;
 };
-
-/** @} */

Sming/Core/Data/Stream/FlashMemoryStream.h

@@ -14,17 +14,8 @@
 
 #include <FlashString/Stream.hpp>
 
-/** @addtogroup stream
- *  @{
+/**
+ * @brief Provides a read-only stream buffer on flash storage
+ * @ingroup stream
  */
-
-/*
- * FlashMemoryDataStream
- *
- * Provides a stream buffer on flash storage, so it's read-only
- *
- */
-
 using FlashMemoryStream = FSTR::Stream;
-
-/** @} */

Sming/Core/Data/Stream/GdbFileStream.cpp

@@ -11,8 +11,6 @@
 #include "GdbFileStream.h"
 #include <gdb/gdb_syscall.h>
 
-/* GdbFileStream */
-
 bool GdbFileStream::open(const String& fileName, FileOpenFlags openFlags)
 {
 	lastError = 0;

Sming/Core/Data/Stream/GdbFileStream.h

@@ -14,8 +14,8 @@
 #include "FileSystem.h"
 
 /**
-  * @ingroup stream gdb_syscall
   * @brief GDB File stream class to provide access to host files whilst running under debugger
+  * @ingroup stream gdb_syscall
  */
 class GdbFileStream : public ReadWriteStream
 {

Sming/Core/Data/Stream/LimitedMemoryStream.h

@@ -12,13 +12,12 @@
 
 #include "ReadWriteStream.h"
 
-/** @addtogroup stream
- *  @{
- */
-
 /**
  * @brief Memory stream that stores limited number of bytes
- * 		  Once the limit is reached the stream will discard incoming bytes on write
+ *
+ * Once the limit is reached the stream will discard incoming bytes on write
+ *
+ * @ingroup stream
  */
 class LimitedMemoryStream : public ReadWriteStream
 {
@@ -32,31 +31,20 @@ class LimitedMemoryStream : public ReadWriteStream
 		delete[] buffer;
 	}
 
-	//Use base class documentation
 	StreamType getStreamType() const override
 	{
 		return eSST_Memory;
 	}
 
-	/**
-	 * @brief Return the total length of the stream
-	 * @retval int -1 is returned when the size cannot be determined
-	 */
 	int available() override
 	{
 		return writePos - readPos;
 	}
 
 	uint16_t readMemoryBlock(char* data, int bufSize) override;
 
-	//Use base class documentation
 	bool seek(int len) override;
 
-	/** @brief  Write chars to stream
-	 *  @param  buffer Pointer to buffer to write to the stream
-	 *  @param  size Quantity of chars to write
-	 *  @retval size_t Quantity of chars written to stream
-	 */
 	size_t write(const uint8_t* buffer, size_t size) override;
 
 	bool isFinished() override
@@ -70,5 +58,3 @@ class LimitedMemoryStream : public ReadWriteStream
 	size_t readPos = 0;
 	size_t length = 0;
 };
-
-/** @} */

Sming/Core/Data/Stream/MemoryDataStream.cpp

@@ -10,8 +10,6 @@
 
 #include "MemoryDataStream.h"
 
-/* MemoryDataStream */
-
 bool MemoryDataStream::ensureCapacity(size_t minCapacity)
 {
 	if(capacity < minCapacity) {