pkg: enhance doxygen packages documentation

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.

pkg/emb6/doc.txt

@@ -1,8 +1,9 @@
 /**
  * @defgroup pkg_emb6 emb6 network stack
- * @ingroup pkg
+ * @ingroup  pkg
- * @brief   emb6 network stack
+ * @ingroup  net
- * @see     https://github.com/hso-esk/emb6/raw/develop/doc/pdf/emb6.pdf
+ * @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.

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
+ */

pkg/heatshrink/README.md

@@ -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.

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
+ */

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
+ */

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
+ */

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
+ */

pkg/lwip/doc.txt

@@ -1,6 +1,7 @@
 /**
  * @defgroup pkg_lwip   lwIP network stack
- * @ingroup pkg
+ * @ingroup  pkg
- * @brief   Provides the lwIP network stack
+ * @ingroup  net
- * @see     http://savannah.nongnu.org/projects/lwip/
+ * @brief    Provides the lwIP network stack
+ * @see      http://savannah.nongnu.org/projects/lwip/
  */

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
+ */

pkg/minmea/README.md

@@ -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.

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
+ */

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
+ */

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
+ */

pkg/relic/README.md

@@ -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>```.

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
+ */

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
+ */

pkg/tiny-asn1/doc.txt

@@ -1,6 +1,7 @@
 /**
- * @defgroup tiny-asn1 tiny-asn1
+ * @defgroup pkg_tiny-asn1 Lightweight ASN.1 decoding/encoding library
- * @ingroup pkg
+ * @ingroup  pkg
- * @brief   Lightweight ASN.1 decoding/encoding library
+ * @ingroup  sys
- * @see     https://gitlab.com/matthegap/tiny-asn1
+ * @brief    Lightweight ASN.1 decoding/encoding library
+ * @see      https://gitlab.com/matthegap/tiny-asn1
  */

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
+ */

pkg/tweetnacl/README.md

@@ -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>
-```

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/
+ */

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
+ */

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
+ */