From f3856ad70196a5950d2c8f13d3ca5c9407ca7caf Mon Sep 17 00:00:00 2001 From: "Jeroen F.J. Laros" Date: Sat, 18 Nov 2023 17:37:13 +0100 Subject: [PATCH] Documentation. --- .readthedocs.yaml | 16 ++++++++++++ LICENSE.md | 19 ++++++++++++++ README.rst | 40 ++++++++++++++++++++++++++++ docs/Doxyfile | 12 +++++++++ docs/api.rst | 19 ++++++++++++++ docs/conf.py | 13 ++++++++++ docs/credits.rst | 10 +++++++ docs/index.rst | 10 +++++++ docs/install.rst | 46 +++++++++++++++++++++++++++++++++ docs/requirements.txt | 3 +++ docs/usage.rst | 24 +++++++++++++++++ examples/arrayArgument/Makefile | 1 - examples/size/Makefile | 24 ----------------- library.properties | 4 +-- src/span.tcc | 29 ++++++++++++++++++--- 15 files changed, 239 insertions(+), 31 deletions(-) create mode 100644 .readthedocs.yaml create mode 100644 LICENSE.md create mode 100644 README.rst create mode 100644 docs/Doxyfile create mode 100644 docs/api.rst create mode 100644 docs/conf.py create mode 100644 docs/credits.rst create mode 100644 docs/index.rst create mode 100644 docs/install.rst create mode 100644 docs/requirements.txt create mode 100644 docs/usage.rst delete mode 120000 examples/arrayArgument/Makefile delete mode 100644 examples/size/Makefile diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..5c9e53f --- /dev/null +++ b/.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 diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..7f4dd90 --- /dev/null +++ b/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. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..cbff383 --- /dev/null +++ b/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 diff --git a/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 0000000..31168f4 --- /dev/null +++ b/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 diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..b1f202c --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,19 @@ +API documentation +================= + +.. code-block:: cpp + + #include + + +Functions +--------- + +.. doxygenfunction:: arraySize + + +Class definitions +----------------- + +.. doxygenclass:: Span + :members: diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..84e7843 --- /dev/null +++ b/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' diff --git a/docs/credits.rst b/docs/credits.rst new file mode 100644 index 0000000..f8ff179 --- /dev/null +++ b/docs/credits.rst @@ -0,0 +1,10 @@ +Contributors +============ + +- Jeroen F.J. Laros (Original author, maintainer) + +Find out who contributed: + +:: + + git shortlog -s -e diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..f76142e --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,10 @@ +.. include:: ../README.rst + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + install + usage + api + credits diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 0000000..1f667ab --- /dev/null +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..568391f --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +breathe>=4.3.1 +docutils>=0.17.1 +sphinx_rtd_theme diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000..bc26199 --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,24 @@ +Usage +===== + +Include the header file to use the arrayhelpers library. + +.. code-block:: cpp + + #include + + +Examples +-------- + +Array size +~~~~~~~~~~ + +.. literalinclude:: ../examples/size/size.ino + :language: cpp + +Passing an array to a function +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. literalinclude:: ../examples/arrayArgument/arrayArgument.ino + :language: cpp diff --git a/examples/arrayArgument/Makefile b/examples/arrayArgument/Makefile deleted file mode 120000 index d7ef0de..0000000 --- a/examples/arrayArgument/Makefile +++ /dev/null @@ -1 +0,0 @@ -../size/Makefile \ No newline at end of file diff --git a/examples/size/Makefile b/examples/size/Makefile deleted file mode 100644 index 83e4f92..0000000 --- a/examples/size/Makefile +++ /dev/null @@ -1,24 +0,0 @@ -FQBN := arduino:avr:pro -PORT := /dev/ttyUSB0 -BUILD := build -FLAGS := -pedantic - -ARDUINO := arduino-cli -PICOCOM := picocom - -SKETCH := $(wildcard *.ino) -LIBS := $(wildcard *.cpp *.h *.tcc) -HEX := $(BUILD)/$(addsuffix .hex, $(SKETCH)) - - -all: $(HEX) - -$(HEX): $(SKETCH) $(LIBS) - $(ARDUINO) compile --fqbn $(FQBN) --warnings all --output-dir $(BUILD) \ - --build-property compiler.cpp.extra_flags="$(FLAGS)" - -upload: $(HEX) - $(ARDUINO) upload --fqbn $(FQBN) --port $(PORT) --input-file $(HEX) - -comm: - $(PICOCOM) -q $(PORT) diff --git a/library.properties b/library.properties index beb20f6..afcf7e4 100644 --- a/library.properties +++ b/library.properties @@ -1,10 +1,10 @@ -name=arrayhelpers +name=array-helpers version=1.0.0 author=Jeroen F.J. Laros maintainer=Jeroen F.J. Laros 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 diff --git a/src/span.tcc b/src/span.tcc index bc5f787..1c8aceb 100644 --- a/src/span.tcc +++ b/src/span.tcc @@ -1,6 +1,6 @@ #pragma once -/*! A limited implementation of std::span. */ +/*! A limited implementation of `std::span`. */ template 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;