From 2cbeab4521fd8cf1d128994f5cbdc2aef9765d5a Mon Sep 17 00:00:00 2001 From: Martine Lenders Date: Thu, 20 Aug 2015 16:17:37 +0200 Subject: [PATCH 1/2] doc: fix and update net and net_gnrc documentation --- sys/include/net/ethernet.h | 2 +- sys/include/net/gnrc.h | 2 +- sys/include/net/gnrc/icmpv6.h | 8 ++++---- sys/include/net/gnrc/ipv6.h | 6 +++--- sys/include/net/gnrc/ndp.h | 4 ++-- sys/include/net/gnrc/netapi.h | 8 ++++---- sys/include/net/gnrc/netdev.h | 3 ++- sys/include/net/gnrc/netdev_eth.h | 7 +++---- sys/include/net/gnrc/netif.h | 8 ++++---- sys/include/net/gnrc/netreg.h | 3 ++- sys/include/net/gnrc/nettype.h | 2 +- sys/include/net/gnrc/nomac.h | 4 ++-- sys/include/net/gnrc/pkt.h | 8 ++++---- sys/include/net/gnrc/pktbuf.h | 2 +- sys/include/net/gnrc/pktdump.h | 4 ++-- sys/include/net/gnrc/pktqueue.h | 2 +- sys/include/net/gnrc/rpl.h | 5 +++-- sys/include/net/gnrc/sixlowpan.h | 4 ++-- sys/include/net/gnrc/sixlowpan/ctx.h | 3 --- sys/include/net/gnrc/slip.h | 2 +- sys/include/net/gnrc/udp.h | 8 ++++---- sys/include/net/gnrc/zep.h | 2 +- sys/include/net/ndp.h | 2 +- sys/include/net/sixlowpan.h | 4 ++-- sys/include/net/udp.h | 4 ++-- 25 files changed, 53 insertions(+), 54 deletions(-) diff --git a/sys/include/net/ethernet.h b/sys/include/net/ethernet.h index b8513c947b..d3914984ff 100644 --- a/sys/include/net/ethernet.h +++ b/sys/include/net/ethernet.h @@ -9,7 +9,7 @@ /** * @defgroup net_ethernet Ethernet * @ingroup net - * @brief Ethernet implementation + * @brief Provides Ethernet header and helper functions * @{ * * @file diff --git a/sys/include/net/gnrc.h b/sys/include/net/gnrc.h index 8e5da62ac5..8375128231 100644 --- a/sys/include/net/gnrc.h +++ b/sys/include/net/gnrc.h @@ -13,7 +13,7 @@ * @{ * * @file - * @brief Pseudo header that includes all gnrc network stack base modules + * @brief Includes all essential GNRC network stack base modules * * @author Hauke Petersen */ diff --git a/sys/include/net/gnrc/icmpv6.h b/sys/include/net/gnrc/icmpv6.h index 754c2d3f26..f780189804 100644 --- a/sys/include/net/gnrc/icmpv6.h +++ b/sys/include/net/gnrc/icmpv6.h @@ -7,9 +7,9 @@ */ /** - * @defgroup net_gnrc__icmpv6 Internet Control Message Protocol for IPv6 - * @ingroup net_gnrc__ipv6 - * @brief Basic implementation of ICMPv6 + * @defgroup net_gnrc_icmpv6 ICMPv6 + * @ingroup net_gnrc_ipv6 + * @brief GNRC's implementation of ICMPv6 * * @see * RFC 4443 @@ -17,7 +17,7 @@ * @{ * * @file - * @brief Definitions for ICMPv6 + * @brief Definitions for GNRC's ICMPv6 implementation * * @author Martine Lenders * diff --git a/sys/include/net/gnrc/ipv6.h b/sys/include/net/gnrc/ipv6.h index 54c8ae3467..59f3006f6b 100644 --- a/sys/include/net/gnrc/ipv6.h +++ b/sys/include/net/gnrc/ipv6.h @@ -8,8 +8,8 @@ /** * @defgroup net_gnrc_ipv6 IPv6 - * @ingroup net - * @brief New IPv6 implementation + * @ingroup net_gnrc + * @brief GNRC's IPv6 implementation * * The IPv6 control thread understands messages of type * @@ -19,7 +19,7 @@ * @{ * * @file - * @brief Definitions for IPv6 + * @brief Definitions for GNRC's IPv6 implementation * * @author Martine Lenders */ diff --git a/sys/include/net/gnrc/ndp.h b/sys/include/net/gnrc/ndp.h index 078f08d940..bfea5be09e 100644 --- a/sys/include/net/gnrc/ndp.h +++ b/sys/include/net/gnrc/ndp.h @@ -9,11 +9,11 @@ /** * @defgroup net_gnrc_ndp IPv6 Neighbor discovery * @ingroup net_gnrc_icmpv6 - * @brief IPv6 Neighbor Discovery Implementation + * @brief GNRC's IPv6 Neighbor Discovery implementation * @{ * * @file - * @brief Neighbor Discovery definitions + * @brief Definitions for GNRC's IPv6 Neighbor Discovery * * @author Martine Lenders */ diff --git a/sys/include/net/gnrc/netapi.h b/sys/include/net/gnrc/netapi.h index f2318ca171..c6fab3a606 100644 --- a/sys/include/net/gnrc/netapi.h +++ b/sys/include/net/gnrc/netapi.h @@ -7,9 +7,9 @@ */ /** - * @defgroup net_gnrc_netapi Generic network module interface - * @ingroup net - * @brief Generic interface for IPC communication between network modules + * @defgroup net_gnrc_netapi GNRC communication interface + * @ingroup net_gnrc + * @brief Generic interface for IPC communication between GNRC modules * * @details The idea of this interface is that it provides every network * module with a basic set of commands to communicate with its @@ -19,7 +19,7 @@ * @{ * * @file - * @brief Generic interface to communicate with network modules + * @brief Generic interface to communicate with GNRC modules * * @author Martine Lenders * @author Hauke Petersen diff --git a/sys/include/net/gnrc/netdev.h b/sys/include/net/gnrc/netdev.h index b1b265b0b1..f1b5a5997b 100644 --- a/sys/include/net/gnrc/netdev.h +++ b/sys/include/net/gnrc/netdev.h @@ -9,7 +9,8 @@ /** * @defgroup net_gnrc_netdev Network device driver interface - * @ingroup net + * @ingroup net_gnrc + * @brief Common network device interface * @{ * * @file diff --git a/sys/include/net/gnrc/netdev_eth.h b/sys/include/net/gnrc/netdev_eth.h index e6bc89cba7..445df24b42 100644 --- a/sys/include/net/gnrc/netdev_eth.h +++ b/sys/include/net/gnrc/netdev_eth.h @@ -9,11 +9,10 @@ */ /** - * @defgroup gnrc_netdev_eth dev_eth ethernet interface as netdev device. - * @ingroup net + * @defgroup net_gnrc_netdev_eth dev_eth as netdev device. + * @ingroup net_gnrc_netdev * - * @brief Allows for usage of dev_eth ethernet interfaces as ethernet netdev - * devices. + * @brief Allows for usage of @p dev_eth as ethernet netdev devices. * * @{ * diff --git a/sys/include/net/gnrc/netif.h b/sys/include/net/gnrc/netif.h index 2ccf92ddcc..320bba4ea3 100644 --- a/sys/include/net/gnrc/netif.h +++ b/sys/include/net/gnrc/netif.h @@ -8,16 +8,16 @@ /** * @defgroup net_gnrc_netif Network interfaces - * @ingroup net - * @brief Abstraction layer for network interfaces + * @ingroup net_gnrc + * @brief Abstraction layer for GNRC's network interfaces * - * Network interfaces in this context are threads for protocols that are + * Network interfaces in the context of GNRC are threads for protocols that are * below the network layer. * * @{ * * @file - * @brief Definitions for network interfaces + * @brief Definitions for GNRC's network interfaces * * @author Martine Lenders */ diff --git a/sys/include/net/gnrc/netreg.h b/sys/include/net/gnrc/netreg.h index 523be82500..5a8529c854 100644 --- a/sys/include/net/gnrc/netreg.h +++ b/sys/include/net/gnrc/netreg.h @@ -8,7 +8,8 @@ /** * @defgroup net_gnrc_netreg Network protocol registry - * @ingroup net + * @ingroup net_gnrc + * @brief Registry to receive messages of a specified protocol type by GNRC. * @{ * * @file diff --git a/sys/include/net/gnrc/nettype.h b/sys/include/net/gnrc/nettype.h index c969a16fcd..eecda8b142 100644 --- a/sys/include/net/gnrc/nettype.h +++ b/sys/include/net/gnrc/nettype.h @@ -8,7 +8,7 @@ /** * @defgroup net_gnrc_nettype Protocol type - * @ingroup net + * @ingroup net_gnrc * @brief Protocol type definitions to be used with the @ref net_gnrc_netapi, * the @ref net_gnrc_netdev, the @ref net_gnrc_netreg, and * the @ref net_gnrc_pkt diff --git a/sys/include/net/gnrc/nomac.h b/sys/include/net/gnrc/nomac.h index eb40d83964..15ca439cf0 100644 --- a/sys/include/net/gnrc/nomac.h +++ b/sys/include/net/gnrc/nomac.h @@ -7,8 +7,8 @@ */ /** - * @defgroup net_nomac Simplest possible MAC layer - * @ingroup net + * @defgroup net_gnrc_nomac Simplest possible MAC layer + * @ingroup net_gnrc * @brief Simplest possible MAC protocol that sends without considering * the state of the medium * @{ diff --git a/sys/include/net/gnrc/pkt.h b/sys/include/net/gnrc/pkt.h index 4b3488dd3f..9161125f45 100644 --- a/sys/include/net/gnrc/pkt.h +++ b/sys/include/net/gnrc/pkt.h @@ -8,13 +8,13 @@ */ /** - * @defgroup net_gnrc_pkt Packet - * @brief Network packet abstraction types - * @ingroup net + * @defgroup net_gnrc_pkt Packets + * @ingroup net_gnrc_pktbuf + * @brief Network packet abstraction type and helper functions * @{ * * @file - * @brief General definitions for network packets + * @brief General definitions for network packets and their helper functions * * @author Martine Lenders * @author Hauke Petersen diff --git a/sys/include/net/gnrc/pktbuf.h b/sys/include/net/gnrc/pktbuf.h index a5ab8b1025..6234e1c0e7 100644 --- a/sys/include/net/gnrc/pktbuf.h +++ b/sys/include/net/gnrc/pktbuf.h @@ -9,7 +9,7 @@ /** * @defgroup net_gnrc_pktbuf Packet buffer - * @ingroup net + * @ingroup net_gnrc * @brief A global network packet buffer. * * @note **WARNING!!** Do not store data structures that are not packed diff --git a/sys/include/net/gnrc/pktdump.h b/sys/include/net/gnrc/pktdump.h index b1a8501366..02b5da9d56 100644 --- a/sys/include/net/gnrc/pktdump.h +++ b/sys/include/net/gnrc/pktdump.h @@ -7,8 +7,8 @@ */ /** - * @defgroup net_pktdump Dump Network Packets - * @ingroup net + * @defgroup net_gnrc_pktdump Dump Network Packets + * @ingroup net_gnrc * @brief Dump network packets to STDOUT for debugging * * @{ diff --git a/sys/include/net/gnrc/pktqueue.h b/sys/include/net/gnrc/pktqueue.h index 9175a48180..e70deb326d 100644 --- a/sys/include/net/gnrc/pktqueue.h +++ b/sys/include/net/gnrc/pktqueue.h @@ -8,8 +8,8 @@ /** * @defgroup net_gnrc_pktqueue Packet Queue + * @ingroup net_gnrc * @brief Packet wrapper for the Priority Queue - * @ingroup net * @{ * * @file diff --git a/sys/include/net/gnrc/rpl.h b/sys/include/net/gnrc/rpl.h index 0b681ebfee..cb958753ef 100644 --- a/sys/include/net/gnrc/rpl.h +++ b/sys/include/net/gnrc/rpl.h @@ -9,8 +9,9 @@ */ /** - * @defgroup net_gnrc_rpl New RPL - * @ingroup net + * @defgroup net_gnrc_rpl RPL + * @ingroup net_gnrc + * @brief RPL implementation for GNRC * @{ * * @file diff --git a/sys/include/net/gnrc/sixlowpan.h b/sys/include/net/gnrc/sixlowpan.h index daddb4bea8..f7cb8e2ce2 100644 --- a/sys/include/net/gnrc/sixlowpan.h +++ b/sys/include/net/gnrc/sixlowpan.h @@ -8,8 +8,8 @@ /** * @defgroup net_gnrc_sixlowpan 6LoWPAN - * @ingroup net - * @brief 6LoWPAN implementation + * @ingroup net_gnrc + * @brief GNRC's 6LoWPAN implementation * @{ * * @file diff --git a/sys/include/net/gnrc/sixlowpan/ctx.h b/sys/include/net/gnrc/sixlowpan/ctx.h index 61bab92e1a..cae1e3e1c6 100644 --- a/sys/include/net/gnrc/sixlowpan/ctx.h +++ b/sys/include/net/gnrc/sixlowpan/ctx.h @@ -7,9 +7,6 @@ */ /** - * @defgroup net_gnrc_sixlowpan 6LoWPAN - * @ingroup net - * * @defgroup net_gnrc_sixlowpan_ctx Contexts for 6LoWPAN address compression * @ingroup net_gnrc_sixlowpan * @brief Context buffer for stateful 6LoWPAN address compression diff --git a/sys/include/net/gnrc/slip.h b/sys/include/net/gnrc/slip.h index ca9039c79b..0fec429529 100644 --- a/sys/include/net/gnrc/slip.h +++ b/sys/include/net/gnrc/slip.h @@ -8,7 +8,7 @@ /** * @defgroup net_gnrc_slip SLIP - * @ingroup net + * @ingroup net_gnrc * @brief Provides a SLIP interface over UART utilizing * @ref driver_periph_uart. * @see RFC 1055 diff --git a/sys/include/net/gnrc/udp.h b/sys/include/net/gnrc/udp.h index 9e4158f291..f53e7f6eff 100644 --- a/sys/include/net/gnrc/udp.h +++ b/sys/include/net/gnrc/udp.h @@ -7,14 +7,14 @@ */ /** - * @defgroup sys_net_udp UDP - * @ingroup net - * @brief RIOT's implementation of the UDP protocol + * @defgroup net_gnrc_udp UDP + * @ingroup net_gnrc + * @brief GNRC's implementation of the UDP protocol * * @{ * * @file - * @brief UDP interface definition + * @brief UDP GNRC definition * * @author Hauke Petersen */ diff --git a/sys/include/net/gnrc/zep.h b/sys/include/net/gnrc/zep.h index 76099bf375..8195bb1b6e 100644 --- a/sys/include/net/gnrc/zep.h +++ b/sys/include/net/gnrc/zep.h @@ -8,7 +8,7 @@ /** * @defgroup net_gnrc_zep Zigbee Encapsulation Protocol - * @ingroup net + * @ingroup net_gnrc * @brief Transports IEEE 802.15.4 frames over UDP (can be parsed by * Wireshark) * @note Stability uncertain diff --git a/sys/include/net/ndp.h b/sys/include/net/ndp.h index 70a3cdb31c..f0674d5681 100644 --- a/sys/include/net/ndp.h +++ b/sys/include/net/ndp.h @@ -7,7 +7,7 @@ */ /** - * @defgroup net_ndp IPv6 neighbor discovery messages + * @defgroup net_ndp IPv6 neighbor discovery * @ingroup net_ipv6 * @brief Provides IPv6 neighbor discovery message types * @{ diff --git a/sys/include/net/sixlowpan.h b/sys/include/net/sixlowpan.h index 3c0860be12..0a7b7d478b 100644 --- a/sys/include/net/sixlowpan.h +++ b/sys/include/net/sixlowpan.h @@ -9,11 +9,11 @@ /** * @defgroup net_sixlowpan 6LoWPAN * @ingroup net - * @brief Generic 6LoWPAN types and helper functions + * @brief Provides 6LoWPAN dispatch types and helper functions * @{ * * @file - * @brief 6LoWPAN type and helper function definitons. + * @brief 6LoWPAN dispatch type and helper function definitons. * * @author Martine Lenders */ diff --git a/sys/include/net/udp.h b/sys/include/net/udp.h index 636797ead2..836dd2d747 100644 --- a/sys/include/net/udp.h +++ b/sys/include/net/udp.h @@ -9,14 +9,14 @@ /** * @defgroup net_udp UDP * @ingroup net - * @brief UDP header definition + * @brief Provides UDP header and helper functions * @see * RFC 768 * * @{ * * @file - * @brief UDP header definition + * @brief UDP header and helper functions definition * * @author Martine Lenders */ From 4f68b81361d535a12d7ddd196c927f8fb1b4cc31 Mon Sep 17 00:00:00 2001 From: Martine Lenders Date: Fri, 21 Aug 2015 01:17:10 +0200 Subject: [PATCH 2/2] doc: expand nettype doc + simplify @brief --- sys/include/net/gnrc/nettype.h | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/sys/include/net/gnrc/nettype.h b/sys/include/net/gnrc/nettype.h index eecda8b142..110dfd67f9 100644 --- a/sys/include/net/gnrc/nettype.h +++ b/sys/include/net/gnrc/nettype.h @@ -9,9 +9,12 @@ /** * @defgroup net_gnrc_nettype Protocol type * @ingroup net_gnrc - * @brief Protocol type definitions to be used with the @ref net_gnrc_netapi, - * the @ref net_gnrc_netdev, the @ref net_gnrc_netreg, and - * the @ref net_gnrc_pkt + * @brief Protocol type definitions and helper functions + * + * The protocol types are used with the @ref net_gnrc_netapi, the @ref net_gnrc_netdev, + * the @ref net_gnrc_netreg, and the @ref net_gnrc_pkt to identify network protocols + * throughout the network stack. + * * @{ * * @file