From 539b0c46ff3b300fe2ea8d5cef4b8697b1761e81 Mon Sep 17 00:00:00 2001 From: Jukka Rissanen Date: Thu, 20 Jul 2017 16:29:45 +0300 Subject: [PATCH] net: doc: Add missing defgroups to network header files 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 --- .known-issues/doc/networking.conf | 64 +++++++++++++++++++ doc/api/networking.rst | 101 ++++++++++++++++++++++++++++++ include/net/arp.h | 10 +++ include/net/buf.h | 10 +++ include/net/ethernet.h | 10 +++ include/net/http.h | 10 +++ include/net/ieee802154.h | 10 +++ include/net/ieee802154_radio.h | 9 +++ include/net/mii.h | 9 +++ include/net/mqtt_types.h | 3 +- include/net/net_app.h | 10 +++ include/net/net_core.h | 10 +++ include/net/net_event.h | 9 +++ include/net/net_l2.h | 10 +++ include/net/net_linkaddr.h | 10 +++ include/net/net_offload.h | 10 +++ include/net/net_pkt.h | 10 +++ include/net/net_stats.h | 10 +++ include/net/trickle.h | 10 +++ include/net/udp.h | 11 ++++ include/net/zoap_link_format.h | 3 +- 21 files changed, 335 insertions(+), 4 deletions(-) diff --git a/.known-issues/doc/networking.conf b/.known-issues/doc/networking.conf index 22a584c8f65..1a2de224b4a 100644 --- a/.known-issues/doc/networking.conf +++ b/.known-issues/doc/networking.conf @@ -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[-._/\w]+/doc/api/networking.rst):(?P[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[-._/\w]+/doc/api/networking.rst):(?P[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[-._/\w]+/doc/api/networking.rst):(?P[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]*\^ diff --git a/doc/api/networking.rst b/doc/api/networking.rst index 2fa328b30a4..1911cdb232f 100644 --- a/doc/api/networking.rst +++ b/doc/api/networking.rst @@ -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: diff --git a/include/net/arp.h b/include/net/arp.h index 5ffc507c780..3ab26cc2978 100644 --- a/include/net/arp.h +++ b/include/net/arp.h @@ -21,6 +21,12 @@ extern "C" { #include +/** + * @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(...) diff --git a/include/net/buf.h b/include/net/buf.h index 9372122b568..2eef45c37aa 100644 --- a/include/net/buf.h +++ b/include/net/buf.h @@ -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 diff --git a/include/net/ethernet.h b/include/net/ethernet.h index 8bb6b655cb3..c76f29aa635 100644 --- a/include/net/ethernet.h +++ b/include/net/ethernet.h @@ -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 */ diff --git a/include/net/http.h b/include/net/http.h index ef04eac50bf..52160951cc6 100644 --- a/include/net/http.h +++ b/include/net/http.h @@ -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__ */ diff --git a/include/net/ieee802154.h b/include/net/ieee802154.h index 882f1f79fd0..4f7e6498628 100644 --- a/include/net/ieee802154.h +++ b/include/net/ieee802154.h @@ -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__ */ diff --git a/include/net/ieee802154_radio.h b/include/net/ieee802154_radio.h index 7368e771764..898820ccaa2 100644 --- a/include/net/ieee802154_radio.h +++ b/include/net/ieee802154_radio.h @@ -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__ */ diff --git a/include/net/mii.h b/include/net/mii.h index 34d43e89e2d..4a537d12ddf 100644 --- a/include/net/mii.h +++ b/include/net/mii.h @@ -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_ */ diff --git a/include/net/mqtt_types.h b/include/net/mqtt_types.h index b51f83a7177..5db527fae8a 100644 --- a/include/net/mqtt_types.h +++ b/include/net/mqtt_types.h @@ -14,8 +14,7 @@ extern "C" { #endif /** - * @brief MQTT library - * @defgroup mqtt MQTT library + * @addtogroup mqtt * @{ */ diff --git a/include/net/net_app.h b/include/net/net_app.h index c2ca16a9115..cd2437e80ba 100644 --- a/include/net/net_app.h +++ b/include/net/net_app.h @@ -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 diff --git a/include/net/net_core.h b/include/net/net_core.h index 8cc97c02dcc..5f1ca2842c1 100644 --- a/include/net/net_core.h +++ b/include/net/net_core.h @@ -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 diff --git a/include/net/net_event.h b/include/net/net_event.h index e4038525098..e4de363b147 100644 --- a/include/net/net_event.h +++ b/include/net/net_event.h @@ -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__ */ diff --git a/include/net/net_l2.h b/include/net/net_l2.h index 253cf892f4e..23d65864567 100644 --- a/include/net/net_l2.h +++ b/include/net/net_l2.h @@ -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 diff --git a/include/net/net_linkaddr.h b/include/net/net_linkaddr.h index 336d30665d0..0b15781ba6e 100644 --- a/include/net/net_linkaddr.h +++ b/include/net/net_linkaddr.h @@ -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 diff --git a/include/net/net_offload.h b/include/net/net_offload.h index aed1530acfb..38a6aa007b6 100644 --- a/include/net/net_offload.h +++ b/include/net/net_offload.h @@ -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 @@ -427,4 +433,8 @@ static inline int net_offload_put(struct net_if *iface, #endif /* CONFIG_NET_OFFLOAD */ +/** + * @} + */ + #endif /* __NET_OFFLOAD_H__ */ diff --git a/include/net/net_pkt.h b/include/net/net_pkt.h index 40defb0f7e3..8dacf6e5fc5 100644 --- a/include/net/net_pkt.h +++ b/include/net/net_pkt.h @@ -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 diff --git a/include/net/net_stats.h b/include/net/net_stats.h index 8b524d7f24e..0536ab385aa 100644 --- a/include/net/net_stats.h +++ b/include/net/net_stats.h @@ -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 diff --git a/include/net/trickle.h b/include/net/trickle.h index 72bf5807e79..b4374d0b240 100644 --- a/include/net/trickle.h +++ b/include/net/trickle.h @@ -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 diff --git a/include/net/udp.h b/include/net/udp.h index 637e9d01598..d10e2124893 100644 --- a/include/net/udp.h +++ b/include/net/udp.h @@ -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 diff --git a/include/net/zoap_link_format.h b/include/net/zoap_link_format.h index 5583ea530f5..ce4ec577ab7 100644 --- a/include/net/zoap_link_format.h +++ b/include/net/zoap_link_format.h @@ -18,8 +18,7 @@ extern "C" { #endif /** - * @brief COAP library - * @defgroup zoap COAP Library + * @addtogroup zoap COAP Library * @{ */