Documentation.

.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.9"
+  jobs:
+    pre_build:
+      - doxygen docs/Doxyfile
+
+python:
+   install:
+   - requirements: docs/requirements.txt
+
+sphinx:
+  configuration: docs/conf.py

LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2018 by Jeroen F.J. Laros.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.rst

@@ -0,0 +1,40 @@
+Array helper classes and functions
+==================================
+
+.. image:: https://img.shields.io/github/last-commit/jfjlaros/array-helpers.svg
+   :target: https://github.com/jfjlaros/array-helpers/graphs/commit-activity
+.. image:: https://github.com/jfjlaros/array-helpers/actions/workflows/arduino-package.yml/badge.svg
+   :target: https://github.com/jfjlaros/array-helpers/actions/workflows/arduino-package.yml
+.. image:: https://readthedocs.org/projects/simplerpc/badge/?version=latest
+   :target: https://array-helpers.readthedocs.io/en/latest
+.. image:: https://img.shields.io/github/release-date/jfjlaros/array-helpers.svg
+   :target: https://github.com/jfjlaros/array-helpers/releases
+.. image:: https://img.shields.io/github/release/jfjlaros/array-helpers.svg
+   :target: https://github.com/jfjlaros/array-helpers/releases
+.. image:: https://www.ardu-badge.com/badge/array-helpers.svg
+   :target: https://www.ardu-badge.com/array-helpers
+.. image:: https://img.shields.io/github/languages/code-size/jfjlaros/array-helpers.svg
+   :target: https://github.com/jfjlaros/array-helpers
+.. image:: https://img.shields.io/github/languages/count/jfjlaros/array-helpers.svg
+   :target: https://github.com/jfjlaros/array-helpers
+.. image:: https://img.shields.io/github/languages/top/jfjlaros/array-helpers.svg
+   :target: https://github.com/jfjlaros/array-helpers
+.. image:: https://img.shields.io/github/license/jfjlaros/array-helpers.svg
+   :target: https://raw.githubusercontent.com/jfjlaros/array-helpers/master/LICENSE.md
+
+----
+
+This library provides a number of helper classes and functions to ease working
+with arrays.
+
+
+**Features:**
+
+- ``arraySize`` -- replacement for ``std::size`` [1_].
+- ``Span`` -- replacement for ``std::span`` [2_].
+
+Please note that most if not all of these features will become obsolete once
+the Arduino tool chain migrates to C++20.
+
+.. _1: https://en.cppreference.com/w/cpp/iterator/size
+.. _2: https://en.cppreference.com/w/cpp/container/span

docs/Doxyfile

@@ -0,0 +1,12 @@
+INPUT                  = src/
+OUTPUT_DIRECTORY       = docs/
+
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+GENERATE_XML           = YES
+
+INLINE_GROUPED_CLASSES = YES
+INLINE_SIMPLE_STRUCTS  = YES
+
+EXTENSION_MAPPING      = tcc=C++
+FILE_PATTERNS          = *.c *.cc *.h *.tcc

docs/api.rst

@@ -0,0 +1,19 @@
+API documentation
+=================
+
+.. code-block:: cpp
+
+    #include <arrayhelpers.h>
+
+
+Functions
+---------
+
+.. doxygenfunction:: arraySize
+
+
+Class definitions
+-----------------
+
+.. doxygenclass:: Span
+   :members:

docs/conf.py

@@ -0,0 +1,13 @@
+project = 'array-helpers'
+author = 'Jeroen F.J. Laros'
+copyright = '2019, {}'.format(author)
+
+extensions = ['breathe', 'sphinx_rtd_theme']
+breathe_projects = {'doxygen': 'xml'}
+breathe_default_project = 'doxygen'
+breathe_default_members = ('members',)
+
+master_doc = 'index'
+
+highlight_language = 'none'
+html_theme = 'sphinx_rtd_theme'

docs/credits.rst

@@ -0,0 +1,10 @@
+Contributors
+============
+
+- Jeroen F.J. Laros <jlaros@fixedpoint.nl> (Original author, maintainer)
+
+Find out who contributed:
+
+::
+
+    git shortlog -s -e

docs/index.rst

@@ -0,0 +1,10 @@
+.. include:: ../README.rst
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   install
+   usage
+   api
+   credits

docs/install.rst

@@ -0,0 +1,46 @@
+Installation
+============
+
+Arduino IDE
+-----------
+
+To install this library in the `Arduino IDE`_, please follow these
+comprehensive `installation instructions`_.
+
+
+Arduino CLI
+-----------
+
+The latest version can be installed with the `Arduino CLI`_ interface using the
+following command.
+
+::
+
+    arduino-cli lib install array-helpers
+
+
+Manual installation
+-------------------
+
+Latest release
+~~~~~~~~~~~~~~
+
+Navigate to the `latest release`_ and either download the ``.zip`` or the
+``.tar.gz`` file and unpack the downloaded archive.
+
+From source
+~~~~~~~~~~~
+
+The source is hosted on GitHub_, use the following command to install the
+latest development version.
+
+::
+
+    git clone https://github.com/jfjlaros/array-helpers.git
+
+
+.. _Arduino CLI: https://arduino.github.io/arduino-cli/latest
+.. _Arduino IDE: https://www.arduino.cc/en/Main/Software
+.. _GitHub: https://github.com/jfjlaros/array-helpers.git
+.. _installation instructions: https://www.ardu-badge.com/array-helpers
+.. _latest release: https://github.com/jfjlaros/array-helpers/releases/latest

docs/requirements.txt

@@ -0,0 +1,3 @@
+breathe>=4.3.1
+docutils>=0.17.1
+sphinx_rtd_theme

docs/usage.rst

@@ -0,0 +1,24 @@
+Usage
+=====
+
+Include the header file to use the arrayhelpers library.
+
+.. code-block:: cpp
+
+    #include <arrayhelpers.h>
+
+
+Examples
+--------
+
+Array size
+~~~~~~~~~~
+
+.. literalinclude:: ../examples/size/size.ino
+    :language: cpp
+
+Passing an array to a function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../examples/arrayArgument/arrayArgument.ino
+    :language: cpp

library.properties

@@ -1,10 +1,10 @@
-name=arrayhelpers
+name=array-helpers
 version=1.0.0
 author=Jeroen F.J. Laros <jlaros@fixedpoint.nl>
 maintainer=Jeroen F.J. Laros <jlaros@fixedpoint.nl>
 sentence=Array helper classes and functions.
 paragraph=This library provides a number of helper classes and functions to ease working with arrays.
 category=Other
-url=https://arrayhelpers.readthedocs.io
+url=https://array-helpers.readthedocs.io
 architectures=*
 includes=arrayHelpers.h

src/span.tcc

@@ -1,6 +1,6 @@
 #pragma once
 
-/*! A limited implementation of std::span. */
+/*! A limited implementation of `std::span`. */
 template <class T>
 class Span {
 public:
@@ -16,13 +16,34 @@ public:
   Span(T (&arr)[n]);
 
 
-  T& operator [](size_t const);
-  T const& operator [](size_t const) const;
+  /*! Get a reference to the element indexed by `idx`.
+   *
+   * \param idx Index.
+   *
+   * \return Reference to element.
+   */
+  T& operator [](size_t const idx);
 
+  /*! \copydoc operator[](size_t const) */
+  T const& operator [](size_t const idx) const;
 
+
+  /*! Get a pointer to the start of the array.
+   *
+   * \return Pointer to the start of the array.
+   */
   T* begin();
+
+  /*! Get a pointer to the end of the array.
+   *
+   * \return Pointer to the end of the array.
+   */
   T* end();
+
+  /*! \copydoc begin() */
   T const* begin() const;
+
+  /*! \copydoc end() */
   T const* end() const;
 
 
@@ -34,7 +55,7 @@ public:
 
   /*! Get the number of elements.
    *
-   * \return Span size.
+   * \return Array size.
    */
   size_t size() const;