From c4ebd18be27e58ceb56eb7e61e50da81298dc54b Mon Sep 17 00:00:00 2001 From: Alexandre Abadie <alexandre.abadie@inria.fr> Date: Mon, 3 Jul 2017 01:32:46 +0200 Subject: [PATCH] pkg: enhance doxygen packages documentation --- pkg/ccn-lite/ccn-lite-riot.h | 1 + pkg/emb6/doc.txt | 7 +++-- pkg/fatfs/doc.txt | 7 +++++ pkg/heatshrink/README.md | 9 ------ pkg/heatshrink/doc.txt | 17 +++++++++++ pkg/jerryscript/doc.txt | 7 +++++ pkg/jsmn/doc.txt | 8 ++++++ pkg/libfixmath/doc.txt | 7 +++++ pkg/lwip/doc.txt | 7 +++-- pkg/micro-ecc/doc.txt | 46 +++++++++++++++++++++++++++++ pkg/minmea/README.md | 11 ------- pkg/minmea/doc.txt | 18 ++++++++++++ pkg/nanocoap/doc.txt | 7 +++++ pkg/openthread/doc.txt | 7 +++++ pkg/relic/README.md | 9 ------ pkg/relic/doc.txt | 28 ++++++++++++++++++ pkg/spiffs/doc.txt | 7 +++++ pkg/tiny-asn1/doc.txt | 9 +++--- pkg/tinydtls/doc.txt | 7 +++++ pkg/tlsf/doc.txt | 0 pkg/tweetnacl/README.md | 44 ---------------------------- pkg/tweetnacl/doc.txt | 56 ++++++++++++++++++++++++++++++++++++ pkg/u8g2/doc.txt | 6 ++++ pkg/wakaama/doc.txt | 6 ++++ 24 files changed, 248 insertions(+), 83 deletions(-) create mode 100644 pkg/fatfs/doc.txt delete mode 100644 pkg/heatshrink/README.md create mode 100644 pkg/heatshrink/doc.txt create mode 100644 pkg/jerryscript/doc.txt create mode 100644 pkg/jsmn/doc.txt create mode 100644 pkg/libfixmath/doc.txt create mode 100644 pkg/micro-ecc/doc.txt delete mode 100644 pkg/minmea/README.md create mode 100644 pkg/minmea/doc.txt create mode 100644 pkg/nanocoap/doc.txt create mode 100644 pkg/openthread/doc.txt delete mode 100644 pkg/relic/README.md create mode 100644 pkg/relic/doc.txt create mode 100644 pkg/spiffs/doc.txt create mode 100644 pkg/tinydtls/doc.txt create mode 100644 pkg/tlsf/doc.txt delete mode 100644 pkg/tweetnacl/README.md create mode 100644 pkg/tweetnacl/doc.txt create mode 100644 pkg/u8g2/doc.txt create mode 100644 pkg/wakaama/doc.txt diff --git a/pkg/ccn-lite/ccn-lite-riot.h b/pkg/ccn-lite/ccn-lite-riot.h index 96e3b1c034..71aa14e253 100644 --- a/pkg/ccn-lite/ccn-lite-riot.h +++ b/pkg/ccn-lite/ccn-lite-riot.h @@ -12,6 +12,7 @@ /** * @defgroup pkg_ccnlite CCN-Lite stack * @ingroup pkg + * @ingroup net * @brief Provides a NDN implementation * * This package provides the CCN-Lite stack as a port of NDN for RIOT. diff --git a/pkg/emb6/doc.txt b/pkg/emb6/doc.txt index 8afb9ee9db..15945ac537 100644 --- a/pkg/emb6/doc.txt +++ b/pkg/emb6/doc.txt @@ -1,8 +1,9 @@ /** * @defgroup pkg_emb6 emb6 network stack - * @ingroup pkg - * @brief emb6 network stack - * @see https://github.com/hso-esk/emb6/raw/develop/doc/pdf/emb6.pdf + * @ingroup pkg + * @ingroup net + * @brief emb6 network stack + * @see https://github.com/hso-esk/emb6/raw/develop/doc/pdf/emb6.pdf * * emb6 is a fork of Contiki's uIP network stack without its usage of * proto-threads. It uses periodic event polling instead. diff --git a/pkg/fatfs/doc.txt b/pkg/fatfs/doc.txt new file mode 100644 index 0000000000..c47dc6e4ab --- /dev/null +++ b/pkg/fatfs/doc.txt @@ -0,0 +1,7 @@ +/** + * @defgroup pkg_fatfs FAT file system + * @ingroup pkg + * @ingroup sys + * @brief Provides FAT file system support + * @see http://elm-chan.org/fsw/ff/00index_e.html + */ \ No newline at end of file diff --git a/pkg/heatshrink/README.md b/pkg/heatshrink/README.md deleted file mode 100644 index 357fd92795..0000000000 --- a/pkg/heatshrink/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Introduction - -This package provides a compression library specifically developed for -memory-constrained devices. See https://github.com/atomicobject/heatshrink for -more information. - -# License - -The library is ISC licensed. diff --git a/pkg/heatshrink/doc.txt b/pkg/heatshrink/doc.txt new file mode 100644 index 0000000000..14dbe84474 --- /dev/null +++ b/pkg/heatshrink/doc.txt @@ -0,0 +1,17 @@ +/** + * @defgroup pkg_heatshrink Lightweight compression library + * @ingroup pkg + * @ingroup sys + * @brief Provides a lightweight compression library to RIOT + * + * # Introduction + * + * This package provides a compression library specifically developed for + * memory-constrained devices. + * + * # License + * + * The library is ISC licensed. + * + * @see https://github.com/atomicobject/heatshrink + */ \ No newline at end of file diff --git a/pkg/jerryscript/doc.txt b/pkg/jerryscript/doc.txt new file mode 100644 index 0000000000..124bd18fb4 --- /dev/null +++ b/pkg/jerryscript/doc.txt @@ -0,0 +1,7 @@ +/** + * @defgroup pkg_jerryscript Ultra-lightweight Javascript for Internet Of Things + * @ingroup pkg + * @ingroup sys + * @brief Provides Javascript support for RIOT + * @see https://github.com/jerryscript-project/jerryscript + */ \ No newline at end of file diff --git a/pkg/jsmn/doc.txt b/pkg/jsmn/doc.txt new file mode 100644 index 0000000000..76cbd8a10e --- /dev/null +++ b/pkg/jsmn/doc.txt @@ -0,0 +1,8 @@ +/** + * @defgroup pkg_jsmn JSON parser library + * @ingroup pkg + * @ingroup sys + * @brief Provides a JSON parser library to RIOT + * + * @see https://github.com/zserge/jsmn + */ \ No newline at end of file diff --git a/pkg/libfixmath/doc.txt b/pkg/libfixmath/doc.txt new file mode 100644 index 0000000000..caff4a6e69 --- /dev/null +++ b/pkg/libfixmath/doc.txt @@ -0,0 +1,7 @@ +/** + * @defgroup pkg_lib_fix_math Cross platform fixed point maths library + * @ingroup pkg + * @ingroup sys + * @brief Provides a cross platform fixed point maths library to RIOT. + * @see https://github.com/PetteriAimonen/libfixmath + */ \ No newline at end of file diff --git a/pkg/lwip/doc.txt b/pkg/lwip/doc.txt index 7c603ca11d..af79f3d8f2 100644 --- a/pkg/lwip/doc.txt +++ b/pkg/lwip/doc.txt @@ -1,6 +1,7 @@ /** * @defgroup pkg_lwip lwIP network stack - * @ingroup pkg - * @brief Provides the lwIP network stack - * @see http://savannah.nongnu.org/projects/lwip/ + * @ingroup pkg + * @ingroup net + * @brief Provides the lwIP network stack + * @see http://savannah.nongnu.org/projects/lwip/ */ diff --git a/pkg/micro-ecc/doc.txt b/pkg/micro-ecc/doc.txt new file mode 100644 index 0000000000..656506024d --- /dev/null +++ b/pkg/micro-ecc/doc.txt @@ -0,0 +1,46 @@ +/** + * @defgroup pkg_micro_ecc Micro-ECC for RIOT + * @ingroup pkg + * @ingroup sys + * @brief Micro-ECC for RIOT + * + * # Micro-ECC for RIOT + * + * This port of Micro-ECC to RIOT is based on the Micro-ECC + * [upstream](https://github.com/kmackay/micro-ecc) and adds `hwrng_read` + * (provided by RIOT) as the default RNG function if it is available on the target + * platform. This port also fixes a minor issue with unused variables in the + * upstream code. + * + * # Usage + * + * ## Build + * + * Add + * ```Makefile + * USEPKG += micro-ecc + * ``` + * to your Makefile. + * + * ## Choosing the right API + * + * Before using the Micro-ECC library, you need to check the `Makefile.features` + * of your target board to see if `periph_hwrng` is provided. + * + * If it is provided, you may safely use `uECC_make_key` to generate ECDSA key + * pairs and call `uECC_sign`/`uECC_verify` to sign/verify the ECDSA signatures. + * + * If not, you cannot use `uECC_make_key` or `uECC_sign` APIs anymore. The ECDSA + * keys have to be generated on a platform with HWRNG support (e.g., `native`) and + * transferred to your target device. You need to use `uECC_sign_deterministic` to + * perform ECDSA deterministic signing (standardized by RFC 6979). You can still + * use `uECC_verify` to verify the signatures from both signing APIs. + * + * **WARNING** Calling `uECC_make_key` and `uECC_sign` APIs on platforms without + * HWRNG support will lead to compile failure. + * + * Examples of using these uECC APIs can be found in the `test` folder of the + * Micro-ECC upstream. + * + * @see https://github.com/kmackay/micro-ecc + */ \ No newline at end of file diff --git a/pkg/minmea/README.md b/pkg/minmea/README.md deleted file mode 100644 index f4285d7a28..0000000000 --- a/pkg/minmea/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# Introduction - -"Minmea is a minimalistic GPS parser library written in pure C intended for -resource-constrained platforms, especially microcontrollers and other embedded -systems." - -See https://github.com/cloudyourcar/minmea for more information. - -# License - -Licensed under WTFPL. diff --git a/pkg/minmea/doc.txt b/pkg/minmea/doc.txt new file mode 100644 index 0000000000..db71764e21 --- /dev/null +++ b/pkg/minmea/doc.txt @@ -0,0 +1,18 @@ +/** + * @defgroup pkg_minmea GPS parser library + * @ingroup pkg + * @ingroup sys + * @brief Provides a GPS parser library to RIOT + * + * # Introduction + * + * "Minmea is a minimalistic GPS parser library written in pure C intended for + * resource-constrained platforms, especially microcontrollers and other embedded + * systems." + * + * # License + * + * Licensed under WTFPL. + * + * @see https://github.com/cloudyourcar/minmea + */ \ No newline at end of file diff --git a/pkg/nanocoap/doc.txt b/pkg/nanocoap/doc.txt new file mode 100644 index 0000000000..7ba479a6f2 --- /dev/null +++ b/pkg/nanocoap/doc.txt @@ -0,0 +1,7 @@ +/** + * @defgroup pkg_nanocoap CoAP lightweight implementation + * @ingroup pkg + * @ingroup net + * @brief Provides a low-level and lightweight implementation of CoAP + * @see https://github.com/kaspar030/sock/tree/master/nanocoap + */ \ No newline at end of file diff --git a/pkg/openthread/doc.txt b/pkg/openthread/doc.txt new file mode 100644 index 0000000000..f9b2b709d4 --- /dev/null +++ b/pkg/openthread/doc.txt @@ -0,0 +1,7 @@ +/** + * @defgroup pkg_openthread OpenThread network stack + * @ingroup pkg + * @ingroup net + * @brief Provides a RIOT adaption of the OpenThread network stack + * @see https://github.com/openthread/openthread + */ \ No newline at end of file diff --git a/pkg/relic/README.md b/pkg/relic/README.md deleted file mode 100644 index aa25d94f01..0000000000 --- a/pkg/relic/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Configuration Options -You can pass along configuration flags for RELIC from your project makefile via: - -```export RELIC_CONFIG_FLAGS=-DARCH=NONE -DQUIET=off -DWORD=32 -DFP_PRIME=255 -DWITH="BN;MD;DV;FP;EP;CP;BC;EC" -DSEED=ZERO``` - -This should happen before the ```USEPKG``` line. - -# Usage -Just put ```USEPKG += relic``` in your Makefile and ```#include <relic.h>```. \ No newline at end of file diff --git a/pkg/relic/doc.txt b/pkg/relic/doc.txt new file mode 100644 index 0000000000..ad0a2de821 --- /dev/null +++ b/pkg/relic/doc.txt @@ -0,0 +1,28 @@ +/** + * @defgroup pkg_relic Relic toolkit for RIOT + * @ingroup pkg + * @ingroup sys + * @brief Provides the Relic cryptographic toolkit to RIOT + * + * + * # Configuration Options + * You can pass along configuration flags for RELIC from your project makefile via: + * ``` + * export RELIC_CONFIG_FLAGS=-DARCH=NONE -DQUIET=off -DWORD=32 -DFP_PRIME=255 -DWITH="BN;MD;DV;FP;EP;CP;BC;EC" -DSEED=ZERO + * ``` + * + * This should happen before the ```USEPKG``` line. + * + * # Usage + * Just put + * ``` + * USEPKG += relic + * ``` + * in your Makefile and + * ```c + * #include <relic.h> + * ``` + * in your `main.c`. + * + * @see https://github.com/relic-toolkit/relic + */ \ No newline at end of file diff --git a/pkg/spiffs/doc.txt b/pkg/spiffs/doc.txt new file mode 100644 index 0000000000..bf6d836a66 --- /dev/null +++ b/pkg/spiffs/doc.txt @@ -0,0 +1,7 @@ +/** + * @defgroup pkg_spiffs SPI flash file system + * @ingroup pkg + * @ingroup sys + * @brief Provides a file system for SPI NOR flash devices + * @see https://github.com/pellepl/spiffs + */ \ No newline at end of file diff --git a/pkg/tiny-asn1/doc.txt b/pkg/tiny-asn1/doc.txt index a47531cd90..7ce634813b 100644 --- a/pkg/tiny-asn1/doc.txt +++ b/pkg/tiny-asn1/doc.txt @@ -1,6 +1,7 @@ /** - * @defgroup tiny-asn1 tiny-asn1 - * @ingroup pkg - * @brief Lightweight ASN.1 decoding/encoding library - * @see https://gitlab.com/matthegap/tiny-asn1 + * @defgroup pkg_tiny-asn1 Lightweight ASN.1 decoding/encoding library + * @ingroup pkg + * @ingroup sys + * @brief Lightweight ASN.1 decoding/encoding library + * @see https://gitlab.com/matthegap/tiny-asn1 */ diff --git a/pkg/tinydtls/doc.txt b/pkg/tinydtls/doc.txt new file mode 100644 index 0000000000..095b13a707 --- /dev/null +++ b/pkg/tinydtls/doc.txt @@ -0,0 +1,7 @@ +/** + * @defgroup pkg_tinydtls TinyDTLS for RIOT + * @ingroup pkg + * @ingroup net + * @brief Provides the Eclipse TinyDTLS to RIOT + * @see https://projects.eclipse.org/projects/iot.tinydtls + */ \ No newline at end of file diff --git a/pkg/tlsf/doc.txt b/pkg/tlsf/doc.txt new file mode 100644 index 0000000000..e69de29bb2 diff --git a/pkg/tweetnacl/README.md b/pkg/tweetnacl/README.md deleted file mode 100644 index 2ddd90b5cf..0000000000 --- a/pkg/tweetnacl/README.md +++ /dev/null @@ -1,44 +0,0 @@ -# TweetNaCl RIOT package -TweetNaCl is the world's first auditable high-security cryptographic library. -TweetNaCl fits into just 100 tweets while supporting all 25 of the C NaCl -functions used by applications. TweetNaCl is a self-contained public-domain C -library, so it can easily be integrated into applications. - -NaCl (pronounced "salt") is a new easy-to-use high-speed software library for -network communication, encryption, decryption, signatures, etc. NaCl's goal is -to provide all of the core operations needed to build higher-level -cryptographic tools. - -Of course, other libraries already exist for these core operations. NaCl -advances the state of the art by improving security, by improving usability, -and by improving speed. - -(from https://nacl.cr.yp.to/ and http://tweetnacl.cr.yp.to/) - -You can find the API and more information [here](https://nacl.cr.yp.to/), since -the sources are not documented due to the aim for fitting in 100 tweets. - -## Requirements -TweetNaCl requires more than 2K of stack, so beware that you're allocating at -least `THREAD_STACKSIZE_DEFAULT + 2048` bytes. - -You can do it easily by adding: - -```makefile -CFLAGS += '-DTHREAD_STACKSIZE_MAIN=(THREAD_STACKSIZE_DEFAULT + 2048)' -``` - -to your makefile. - -## Usage -Just add it as a package in your application: - -```makefile -USEPKG += tweetnacl -``` - -And don't forget to include the header: - -```c -#include <tweetnacl.h> -``` diff --git a/pkg/tweetnacl/doc.txt b/pkg/tweetnacl/doc.txt new file mode 100644 index 0000000000..d74f0665f6 --- /dev/null +++ b/pkg/tweetnacl/doc.txt @@ -0,0 +1,56 @@ +/** + * @defgroup pkg_tweetnacl TweetNaCl high-security cryptographic library + * @ingroup pkg + * @ingroup sys + * @brief Provides the TweetNaCl high-security cryptographic library. + * + * # TweetNaCl RIOT package + * + * TweetNaCl is the world's first auditable high-security cryptographic library. + * TweetNaCl fits into just 100 tweets while supporting all 25 of the C NaCl + * functions used by applications. TweetNaCl is a self-contained public-domain C + * library, so it can easily be integrated into applications. + * + * NaCl (pronounced "salt") is a new easy-to-use high-speed software library for + * network communication, encryption, decryption, signatures, etc. NaCl's goal is + * to provide all of the core operations needed to build higher-level + * cryptographic tools. + * + * Of course, other libraries already exist for these core operations. NaCl + * advances the state of the art by improving security, by improving usability, + * and by improving speed. + * + * (from https://nacl.cr.yp.to/ and http://tweetnacl.cr.yp.to/) + * + * You can find the API and more information [here](https://nacl.cr.yp.to/), since + * the sources are not documented due to the aim for fitting in 100 tweets. + * + * ## Requirements + * + * TweetNaCl requires more than 2K of stack, so beware that you're allocating at + * least `THREAD_STACKSIZE_DEFAULT + 2048` bytes. + * + * You can do it easily by adding: + * + * ```makefile + * CFLAGS += '-DTHREAD_STACKSIZE_MAIN=(THREAD_STACKSIZE_DEFAULT + 2048)' + * ``` + * + * to your makefile. + * + * ## Usage + * + * Just add it as a package in your application: + * + * ```makefile + * USEPKG += tweetnacl + * ``` + * + * And don't forget to include the header: + * + * ```c + * #include <tweetnacl.h> + * ``` + * + * @see https://tweetnacl.cr.yp.to/ + */ \ No newline at end of file diff --git a/pkg/u8g2/doc.txt b/pkg/u8g2/doc.txt new file mode 100644 index 0000000000..459b9b1ce7 --- /dev/null +++ b/pkg/u8g2/doc.txt @@ -0,0 +1,6 @@ +/** + * @defgroup pkg_u8g2 U8G2 graphic library for monochome displays + * @ingroup pkg + * @brief Provides a monochrome graphics library for OLED and LCD displays + * @see https://github.com/olikraus/u8g2 + */ \ No newline at end of file diff --git a/pkg/wakaama/doc.txt b/pkg/wakaama/doc.txt new file mode 100644 index 0000000000..9cd510554c --- /dev/null +++ b/pkg/wakaama/doc.txt @@ -0,0 +1,6 @@ +/** + * @defgroup pkg_wakaama Wakaama LwM2M implementation + * @ingroup pkg + * @brief Provides the Wakaama implementation of LwM2M + * @see https://github.com/eclipse/wakaama + */ \ No newline at end of file -- GitLab