Skip to content

Commit

Permalink
Documentation fixes (#2116)
Browse files Browse the repository at this point in the history
* Add missing library README files and fix headings so index is generated correctly

* Don't emit doxygen members, etc. by default

Otherwise cannot then omit members, which for stream documentation makes it unusable.

* Add upgrade notes and streams page to docs.

* Be consistent with doxygen comments

Don't repeat comments from inherited classes unless there is something to add.
This means we must explicitly add `:members:` declarations if required.

* Fix typo in SSL upgrade notes

* Fix link in wstring.rst

* Review changes

* Fixes from final readthrough
  • Loading branch information
mikee47 authored Oct 19, 2020

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
1 parent ae02fc6 commit b3893e0
Showing 90 changed files with 277 additions and 181 deletions.
4 changes: 4 additions & 0 deletions Sming/Arch/Esp32/Components/esp_idf/README.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
ESP IDF
=======

Provides make targets which are redirected to the ESP IDF.
4 changes: 4 additions & 0 deletions Sming/Arch/Esp32/Components/esp_spiffs/README.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
Esp32 SPIFFS
============

SPIFFS implementation for ESP32 devices.
1 change: 1 addition & 0 deletions Sming/Arch/Esp8266/Components/driver/gpio.rst
Original file line number Diff line number Diff line change
@@ -5,3 +5,4 @@ SDK definitions for GPIO.

.. doxygengroup:: gpio_driver
:content-only:
:members:
1 change: 1 addition & 0 deletions Sming/Arch/Esp8266/Components/driver/hw_timer.rst
Original file line number Diff line number Diff line change
@@ -27,3 +27,4 @@ API Documentation

.. doxygengroup:: hw_timer
:content-only:
:members:
1 change: 1 addition & 0 deletions Sming/Arch/Esp8266/Components/driver/i2s.rst
Original file line number Diff line number Diff line change
@@ -62,3 +62,4 @@ API Documentation

.. doxygengroup:: i2s_driver
:content-only:
:members:
1 change: 1 addition & 0 deletions Sming/Arch/Esp8266/Components/driver/os_timer.rst
Original file line number Diff line number Diff line change
@@ -3,3 +3,4 @@ OS Timer

.. doxygengroup:: os_timer
:content-only:
:members:
1 change: 1 addition & 0 deletions Sming/Arch/Esp8266/Components/driver/pwm.rst
Original file line number Diff line number Diff line change
@@ -19,3 +19,4 @@ API Documentation

.. doxygengroup:: pwm_driver
:content-only:
:members:
1 change: 1 addition & 0 deletions Sming/Arch/Esp8266/Components/driver/uart.rst
Original file line number Diff line number Diff line change
@@ -5,3 +5,4 @@ Custom asynchronous driver.

.. doxygengroup:: uart_driver
:content-only:
:members:
1 change: 1 addition & 0 deletions Sming/Arch/Esp8266/Components/spi_flash/api.rst
Original file line number Diff line number Diff line change
@@ -3,3 +3,4 @@ API Documentation

.. doxygengroup:: spi_flash
:content-only:
:members:
1 change: 1 addition & 0 deletions Sming/Arch/Esp8266/Components/spi_flash/precache.rst
Original file line number Diff line number Diff line change
@@ -49,3 +49,4 @@ API Documentation

.. doxygengroup:: iram_precache
:content-only:
:members:
1 change: 1 addition & 0 deletions Sming/Arch/Host/Components/driver/gpio.rst
Original file line number Diff line number Diff line change
@@ -9,3 +9,4 @@ API Documentation
-----------------

.. doxygenclass:: DigitalHooks
:members:
Original file line number Diff line number Diff line change
@@ -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:
31 changes: 23 additions & 8 deletions Sming/Components/ssl/adapter.rst
Original file line number Diff line number Diff line change
@@ -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:
3 changes: 2 additions & 1 deletion Sming/Components/ssl/include/Network/Ssl/Alert.h
Original file line number Diff line number Diff line change
@@ -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
6 changes: 6 additions & 0 deletions Sming/Components/ssl/session.rst
Original file line number Diff line number Diff line change
@@ -2,6 +2,12 @@ Session
=======

.. doxygenclass:: Ssl::Session
:members:

.. doxygenclass:: Ssl::SessionId
:members:

.. doxygenstruct:: Ssl::Options
:members:

.. doxygenenum:: MaxBufferSize
7 changes: 4 additions & 3 deletions Sming/Components/ssl/upgrade.rst
Original file line number Diff line number Diff line change
@@ -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::

9 changes: 2 additions & 7 deletions Sming/Core/Data/Stream/Base64OutputStream.h
Original file line number Diff line number Diff line change
@@ -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 = {};
};

/** @} */
12 changes: 5 additions & 7 deletions Sming/Core/Data/Stream/ChunkedStream.h
Original file line number Diff line number Diff line change
@@ -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;
};

/** @} */
18 changes: 8 additions & 10 deletions Sming/Core/Data/Stream/DataSourceStream.h
Original file line number Diff line number Diff line change
@@ -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);
};

/** @} */
9 changes: 2 additions & 7 deletions Sming/Core/Data/Stream/EndlessMemoryStream.h
Original file line number Diff line number Diff line change
@@ -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;
};

/** @} */
9 changes: 2 additions & 7 deletions Sming/Core/Data/Stream/FileStream.h
Original file line number Diff line number Diff line change
@@ -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;
};

/** @} */
15 changes: 3 additions & 12 deletions Sming/Core/Data/Stream/FlashMemoryStream.h
Original file line number Diff line number Diff line change
@@ -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;

/** @} */
2 changes: 0 additions & 2 deletions Sming/Core/Data/Stream/GdbFileStream.cpp
Original file line number Diff line number Diff line change
@@ -11,8 +11,6 @@
#include "GdbFileStream.h"
#include <gdb/gdb_syscall.h>

/* GdbFileStream */

bool GdbFileStream::open(const String& fileName, FileOpenFlags openFlags)
{
lastError = 0;
2 changes: 1 addition & 1 deletion Sming/Core/Data/Stream/GdbFileStream.h
Original file line number Diff line number Diff line change
@@ -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
{
22 changes: 4 additions & 18 deletions Sming/Core/Data/Stream/LimitedMemoryStream.h
Original file line number Diff line number Diff line change
@@ -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;
};

/** @} */
2 changes: 0 additions & 2 deletions Sming/Core/Data/Stream/MemoryDataStream.cpp
Original file line number Diff line number Diff line change
@@ -10,8 +10,6 @@

#include "MemoryDataStream.h"

/* MemoryDataStream */

bool MemoryDataStream::ensureCapacity(size_t minCapacity)
{
if(capacity < minCapacity) {
Loading

0 comments on commit b3893e0

Please sign in to comment.