[riot-notifications] [RIOT-OS/RIOT] gnrc_sixlowpan: document submodules according to #8511 (#10841)

Sebastian Meiling notifications at github.com
Tue Jan 22 12:09:57 CET 2019


smlng requested changes on this pull request.

minor nits. 

In general: (where ever fitting and necessary) be explicit and state how things should be implemented and used, avoid vague or soft language (specifcally for API specs).

> @@ -11,11 +11,45 @@
  * @ingroup     net_gnrc
  * @brief       GNRC's 6LoWPAN implementation
  *
- * This module is for usage with the @ref net_gnrc_netapi.
+ * # Internal API and sub-modules
+ *
+ * Internally, @ref net_gnrc_sixlowpan is sub-divided into several sub-modules.
+ * This implement certain features of the 6LoWPAN standard. Currently

typo, either:

- `this implement[s]`
- `[these] implement`

or for the latter variant: `each implementing ...`



> + *   ([gnrc_sixlowpan_frag](@ref net_gnrc_sixlowpan_frag))
+ * - [Uncompressed IPv6](https://tools.ietf.org/html/rfc4944#section-5.1)
+ *   (as part of the main @ref net_gnrc_sixlowpan module)
+ * - IPv6 datagram compression according to [RFC 6282](https://tools.ietf.org/html/rfc6282)
+ *   aka IPHC ([gnrc_sixlowpan_iphc](@ref net_gnrc_sixlowpan_iphc), IPv6
+ *   extension header NHC currently missing)
+ *
+ * Each sub-module has a `send` and `recv` function prefixed by their
+ * respective sub-module name with the following signatures
+ *
+ * ~~~~~~~~~~~~~~~~~~~~~ {.c}
+ * void send(gnrc_pktsnip_t *pkt, void *ctx, uint8_t page);
+ * void recv(gnrc_pktsnip_t *pkt, void *ctx, uint8_t page);
+ * ~~~~~~~~~~~~~~~~~~~~~
+ *
+ * A 6LoWPAN frame `pkt` is supposed to pass the sub-modules sequentially in

> supposed

? sounds vague, better state explicitly how it should be implemented.

> + * - IPv6 datagram compression according to [RFC 6282](https://tools.ietf.org/html/rfc6282)
+ *   aka IPHC ([gnrc_sixlowpan_iphc](@ref net_gnrc_sixlowpan_iphc), IPv6
+ *   extension header NHC currently missing)
+ *
+ * Each sub-module has a `send` and `recv` function prefixed by their
+ * respective sub-module name with the following signatures
+ *
+ * ~~~~~~~~~~~~~~~~~~~~~ {.c}
+ * void send(gnrc_pktsnip_t *pkt, void *ctx, uint8_t page);
+ * void recv(gnrc_pktsnip_t *pkt, void *ctx, uint8_t page);
+ * ~~~~~~~~~~~~~~~~~~~~~
+ *
+ * A 6LoWPAN frame `pkt` is supposed to pass the sub-modules sequentially in
+ * the order of its dispatches on receive or the step that makes most sense next
+ * on send. After it was passed into another sub-module using the respective
+ * `send`/`recv` function a sub-module is not supposed to operate on `pkt`

again, write down how it should be implemented, don't use `supposed`

> + * Each sub-module has a `send` and `recv` function prefixed by their
+ * respective sub-module name with the following signatures
+ *
+ * ~~~~~~~~~~~~~~~~~~~~~ {.c}
+ * void send(gnrc_pktsnip_t *pkt, void *ctx, uint8_t page);
+ * void recv(gnrc_pktsnip_t *pkt, void *ctx, uint8_t page);
+ * ~~~~~~~~~~~~~~~~~~~~~
+ *
+ * A 6LoWPAN frame `pkt` is supposed to pass the sub-modules sequentially in
+ * the order of its dispatches on receive or the step that makes most sense next
+ * on send. After it was passed into another sub-module using the respective
+ * `send`/`recv` function a sub-module is not supposed to operate on `pkt`
+ * anymore.
+ *
+ * The `ctx` parameter can be used to provide data structures of a sub-module to
+ * the next sub-module that might need to modify them (e.g. reassembly

`might` also sounds vague, to me `ctx` should only be used (passed) when the next module must/should modify data structures, hence write `... to the next sub-module if that needs to modify them (e.g. ...`

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/RIOT-OS/RIOT/pull/10841#pullrequestreview-194947701
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.riot-os.org/pipermail/notifications/attachments/20190122/c18780a8/attachment.html>


More information about the notifications mailing list