bartoszek/zephyr
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

net: doc: Add missing defgroups to network header files

Browse Source 
Some of the networking header files in include/net/ directory were
missing @defgroup doxygen directives.

There was also duplicate @defgroup directives which are now changed
to @addtogroup directives.

Added also missing API links to doc/api/networking.rst file.

Added exceptions to .known-issues/doc/networking.conf file so that
doxygen does not complain.

Jira: ZEP-2308

Signed-off-by: Jukka Rissanen <jukka.rissanen@linux.intel.com>
This commit is contained in:
Jukka Rissanen 2017-07-20 16:29:45 +03:00
parent cee4a624f3
commit 539b0c46ff
21 changed files with 335 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
.known-issues/doc/networking.conf
View File

@ -47,3 +47,67 @@
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+]
^.*net_mgmt_event_callback.__unnamed__
^[- \t]*\^
#
# include/net/buf.h
#
^(?P<filename>[-._/\w]+/doc/api/networking.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
^[ \t]*
^[ \t]*\^
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
^[ \t]*
^[ \t]*\^
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+]
^.*net_buf.__unnamed__
^[- \t]*\^
#
# include/net/ieee802154.h
#
^(?P<filename>[-._/\w]+/doc/api/networking.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
^[ \t]*
^[ \t]*\^
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
^[ \t]*
^[ \t]*\^
^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+]
^.*ieee802154_req_params.__unnamed__
^[- \t]*\^
#
# Various warning about net_mgmt declarations
#
^(?P<filename>[-._/\w]+/doc/api/networking.rst):(?P<lineno>[0-9]+): WARNING: Error when parsing function declaration\.
^If the function has no return type\:
^[ \t]*Error in declarator or parameters and qualifiers
^[ \t]*Invalid definition: Expected identifier in nested name\. \[error at [0-9]+\]
^[ \t]*NET_MGMT_DEFINE_.*?$
^[- \t]*\^
#
^If the function has a return type\:
^[ \t]*Error in declarator
^[ \t]*If pointer to member declarator:
^[ \t]*Invalid definition: Expected identifier in nested name\. \[error at [0-9]+\]
^[ \t]*NET_MGMT_DEFINE_.*?$
^[- \t]*\^
#
^[ \t]*If declId, parameters, and qualifiers\:
^[ \t]*Invalid definition: Expected identifier in nested name\. \[error at [0-9]+\]
^[ \t]*NET_MGMT_DEFINE_.*?$
^[- \t]*\^
#
^[ \t]*If parenthesis in noptr-declarator\:
^[ \t]*Error in declarator
^[ \t]*If pointer to member declarator:
^[ \t]*Invalid definition: Expected identifier in nested name\. \[error at [0-9]+\]
^[ \t]*NET_MGMT_DEFINE_.*?$
^[- \t]*\^
#
^[ \t]*If parenthesis in noptr-declarator\:
^[ \t]*Error in declarator or parameters and qualifiers
^[ \t]*If pointer to member declarator:
^[ \t]*Invalid definition: Expected \'\:\:\' in pointer to member \(function\)\. \[error at [0-9]+\]
^[ \t]*NET_MGMT_DEFINE_.*?$
^[- \t]*\^
#
^[ \t]*If declarator-id:
^[ \t]*Invalid definition: Expecting \"\(\" in parameters_and_qualifiers\. \[error at [0-9]+\]
^[ \t]*NET_MGMT_DEFINE_.*?$
^[- \t]*\^

101
doc/api/networking.rst
View File

@ -13,6 +13,27 @@ depends on relevant Kconfig options. For instance IPv6 related
APIs will not be present if :option:`CONFIG_NET_IPV6` has not
been selected.
Network core helpers
********************
.. doxygengroup:: net_core
:project: Zephyr
:content-only:
Network buffers
***************
.. doxygengroup:: net_buf
:project: Zephyr
:content-only:
Network packet management
*************************
.. doxygengroup:: net_pkt
:project: Zephyr
:content-only:
IPv4/IPv6 primitives and helpers
********************************
@ -34,6 +55,20 @@ Network Management
:project: Zephyr
:content-only:
Network layer 2 management
**************************
.. doxygengroup:: net_l2
:project: Zephyr
:content-only:
Network link address
********************
.. doxygengroup:: net_linkaddr
:project: Zephyr
:content-only:
Application network context
***************************
@ -41,9 +76,61 @@ Application network context
:project: Zephyr
:content-only:
Network offloading support
**************************
.. doxygengroup:: net_offload
:project: Zephyr
:content-only:
Network statistics
******************
.. doxygengroup:: net_stats
:project: Zephyr
:content-only:
Trickle timer support
*********************
.. doxygengroup:: trickle
:project: Zephyr
:content-only:
UDP
***
.. doxygengroup:: udp
:project: Zephyr
:content-only:
Network technologies
********************
Ethernet
========
.. doxygengroup:: ethernet
:project: Zephyr
:content-only:
IEEE 802.15.4
=============
.. doxygengroup:: ieee802154
:project: Zephyr
:content-only:
Network and application libraries
*********************************
Network application
===================
.. doxygengroup:: net_app
:project: Zephyr
:content-only:
DHCPv4
======
@ -58,9 +145,23 @@ MQTT 3.1.1
:project: Zephyr
:content-only:
CoAP
====
.. doxygengroup:: zoap
:project: Zephyr
:content-only:
DNS Resolve
===========
.. doxygengroup:: dns_resolve
:project: Zephyr
:content-only:
HTTP
====
.. doxygengroup:: http
:project: Zephyr
:content-only:

10
include/net/arp.h
View File

@ -21,6 +21,12 @@ extern "C" {
#include <net/ethernet.h>
/**
* @brief Address resolution (ARP) library
* @defgroup arp ARP Library
* @{
*/
#define NET_ARP_HDR(pkt) ((struct net_arp_hdr *)net_pkt_ip_data(pkt))
struct net_arp_hdr {
@ -46,6 +52,10 @@ enum net_verdict net_arp_input(struct net_pkt *pkt);
void net_arp_clear_cache(void);
void net_arp_init(void);
/**
* @}
*/
#else /* CONFIG_NET_ARP */
#define net_arp_clear_cache(...)

10
include/net/buf.h
View File

@ -19,6 +19,12 @@
extern "C" {
#endif
/**
* @brief Network buffer library
* @defgroup net_buf Network Buffer Library
* @{
*/
/* Alignment needed for various parts of the buffer definition */
#define __net_buf_align __aligned(sizeof(int))
@ -1022,6 +1028,10 @@ static inline size_t net_buf_frags_len(struct net_buf *buf)
return bytes;
}
/**
* @}
*/
#ifdef __cplusplus
}
#endif

10
include/net/ethernet.h
View File

@ -24,6 +24,12 @@
extern "C" {
#endif
/**
* @brief Ethernet support functions
* @defgroup ethernet Ethernet Support Functions
* @{
*/
#define NET_ETH_HDR(pkt) ((struct net_eth_hdr *)net_pkt_ll(pkt))
#define NET_ETH_PTYPE_ARP 0x0806
@ -72,4 +78,8 @@ const struct net_eth_addr *net_eth_broadcast_addr(void);
}
#endif
/**
* @}
*/
#endif /* __ETHERNET_H */

10
include/net/http.h
View File

@ -13,6 +13,12 @@
extern "C" {
#endif
/**
* @brief HTTP client and server library
* @defgroup http HTTP Library
* @{
*/
#if defined(CONFIG_HTTPS)
#if defined(CONFIG_MBEDTLS)
#if !defined(CONFIG_MBEDTLS_CFG_FILE)
@ -1124,4 +1130,8 @@ int http_server_set_net_pkt_pool(struct http_server_ctx *ctx,
}
#endif
/**
* @}
*/
#endif /* __HTTP_H__ */

10
include/net/ieee802154.h
View File

@ -19,6 +19,12 @@
extern "C" {
#endif
/**
* @brief IEEE 802.15.4 library
* @defgroup ieee802154 IEEE 802.15.4 Library
* @{
*/
#define IEEE802154_MAX_ADDR_LENGTH 8
struct ieee802154_security_ctx {
@ -262,4 +268,8 @@ struct ieee802154_security_params {
}
#endif
/**
* @}
*/
#endif /* __IEEE802154_H__ */

9
include/net/ieee802154_radio.h
View File

@ -19,6 +19,11 @@
extern "C" {
#endif
/**
* @addtogroup ieee802154
* @{
*/
struct ieee802154_radio_api {
/**
* Mandatory to get in first position.
@ -99,4 +104,8 @@ void ieee802154_init(struct net_if *iface);
}
#endif
/**
* @}
*/
#endif /* __IEEE802154_RADIO_H__ */

9
include/net/mii.h
View File

@ -11,6 +11,11 @@
#ifndef _MII_H_
#define _MII_H_
/**
* @addtogroup ethernet
* @{
*/
/* MII management registers */
#define MII_BMCR 0x0 /** Basic Mode Control Register */
#define MII_BMSR 0x1 /** Basic Mode Status Register */
@ -76,4 +81,8 @@
MII_ADVERTISE_100_HALF | MII_ADVERTISE_100_FULL |\
MII_ADVERTISE_SEL_IEEE_802_3)
/**
* @}
*/
#endif /* _MII_H_ */

3
include/net/mqtt_types.h
View File

@ -14,8 +14,7 @@ extern "C" {
#endif
/**
* @brief MQTT library
* @defgroup mqtt MQTT library
* @addtogroup mqtt
* @{
*/

10
include/net/net_app.h
View File

@ -48,6 +48,12 @@
extern "C" {
#endif
/**
* @brief Network application library
* @defgroup net_app Network Application Library
* @{
*/
/** Flags that tell what kind of functionality is needed by the application. */
#define NET_APP_NEED_ROUTER 0x00000001
#define NET_APP_NEED_IPV6 0x00000002
@ -899,6 +905,10 @@ bool net_app_server_tls_disable(struct net_app_ctx *ctx);
#endif /* CONFIG_NET_APP_TLS */
/**
* @}
*/
#ifdef __cplusplus
}
#endif

10
include/net/net_core.h
View File

@ -17,6 +17,12 @@
extern "C" {
#endif
/**
* @brief Network core library
* @defgroup net_core Network Core Library
* @{
*/
/* Network subsystem logging helpers */
#if defined(NET_LOG_ENABLED)
@ -164,6 +170,10 @@ static inline void net_analyze_stack(const char *name,
#endif
/* @endcond */
/**
* @}
*/
#ifdef __cplusplus
}
#endif

9
include/net/net_event.h
View File

@ -16,6 +16,11 @@
extern "C" {
#endif
/**
* @addtogroup net_mgmt
* @{
*/
/* Network Interface events */
#define _NET_IF_LAYER NET_MGMT_LAYER_L1
#define _NET_IF_CORE_CODE 0x001
@ -129,4 +134,8 @@ enum net_event_ipv4_cmd {
}
#endif
/**
* @}
*/
#endif /* __NET_EVENT_H__ */

10
include/net/net_l2.h
View File

@ -18,6 +18,12 @@
extern "C" {
#endif
/**
* @brief Network Layer 2 abstraction layer
* @defgroup net_l2 Network L2 Abstraction Layer
* @{
*/
struct net_if;
struct net_l2 {
@ -101,6 +107,10 @@ extern struct net_l2 __net_l2_end[];
static ctx_type NET_L2_GET_DATA(name, sfx) __used \
__attribute__((__section__(".net_l2.data")));
/**
* @}
*/
#ifdef __cplusplus
}
#endif

10
include/net/net_linkaddr.h
View File

@ -20,6 +20,12 @@
extern "C" {
#endif
/**
* @brief Network link address library
* @defgroup net_linkaddr Network Link Address Library
* @{
*/
#ifdef CONFIG_NET_L2_IEEE802154
#define NET_LINK_ADDR_MAX_LENGTH 8
#else
@ -125,6 +131,10 @@ static inline int net_linkaddr_set(struct net_linkaddr_storage *lladdr_store,
return 0;
}
/**
* @}
*/
#ifdef __cplusplus
}
#endif

10
include/net/net_offload.h
View File

@ -12,6 +12,12 @@
#ifndef __NET_OFFLOAD_H__
#define __NET_OFFLOAD_H__
/**
* @brief Network offloading interface
* @defgroup net_offload Network Offloading Interface
* @{
*/
#if defined(CONFIG_NET_OFFLOAD)
#include <net/buf.h>
@ -427,4 +433,8 @@ static inline int net_offload_put(struct net_if *iface,
#endif /* CONFIG_NET_OFFLOAD */
/**
* @}
*/
#endif /* __NET_OFFLOAD_H__ */

10
include/net/net_pkt.h
View File

@ -31,6 +31,12 @@
extern "C" {
#endif
/**
* @brief Network packet management library
* @defgroup net_pkt Network Packet Library
* @{
*/
struct net_context;
struct net_pkt {
@ -1352,6 +1358,10 @@ const char *net_pkt_pool2str(struct net_buf_pool *pool);
#define net_pkt_print(...)
#endif /* CONFIG_NET_DEBUG_NET_PKT */
/**
* @}
*/
#ifdef __cplusplus
}
#endif

10
include/net/net_stats.h
View File

@ -20,6 +20,12 @@
extern "C" {
#endif
/**
* @brief Network statistics library
* @defgroup net_stats Network Statistics Library
* @{
*/
typedef u32_t net_stats_t;
struct net_stats_bytes {
@ -360,6 +366,10 @@ NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_STATS_GET_RPL);
#endif /* CONFIG_NET_STATISTICS_USER_API */
/**
* @}
*/
#ifdef __cplusplus
}
#endif

10
include/net/trickle.h
View File

@ -23,6 +23,12 @@
extern "C" {
#endif
/**
* @brief Trickle algorithm library
* @defgroup trickle Trickle Algorithm Library
* @{
*/
struct net_trickle;
typedef void (*net_trickle_cb_t)(struct net_trickle *trickle,
@ -120,6 +126,10 @@ static inline bool net_trickle_is_running(struct net_trickle *trickle)
return trickle->I != 0;
}
/**
* @}
*/
#ifdef __cplusplus
}
#endif

11
include/net/udp.h
View File

@ -21,6 +21,12 @@
extern "C" {
#endif
/**
* @brief UDP library
* @defgroup udp UDP Library
* @{
*/
#if defined(CONFIG_NET_UDP)
/**
@ -58,11 +64,16 @@ struct net_udp_hdr *net_udp_get_hdr(struct net_pkt *pkt,
*/
struct net_udp_hdr *net_udp_set_hdr(struct net_pkt *pkt,
struct net_udp_hdr *hdr);
#else
#define net_udp_get_hdr(pkt, frag) NULL
#define net_udp_set_hdr(pkt, frag) NULL
#endif /* CONFIG_NET_UDP */
/**
* @}
*/
#ifdef __cplusplus
}
#endif

3
include/net/zoap_link_format.h
View File

@ -18,8 +18,7 @@ extern "C" {
#endif
/**
* @brief COAP library
* @defgroup zoap COAP Library
* @addtogroup zoap COAP Library
* @{
*/