doc: Include main Network APIs doxygen documentation

Added missing dogygen definitions.

Jira: ZEP-1495

Change-Id: Ibc087f3f174b8af45b0726c0d82b77feff36d4e3
Signed-off-by: Tomasz Bursztyka <tomasz.bursztyka@linux.intel.com>

.known-issues/doc/networking.conf

@@ -0,0 +1,37 @@
+#
+# Networking
+#
+#
+# include/net/net_ip.h warnings
+#
+^(?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 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]+]
+^.*in[_6]+addr.in[46]_u
+^[- \t]*\^
+#
+# include/net/net_if.h warnings
+#
+^(?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, got keyword: struct \[error at [0-9]+]
+^.*struct net_if __aligned\(32\)
+^[- \t]*\^
+^\If the function has a return type:
+^[ \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]+]
+^.*struct net_if __aligned\(32\)
+^[- \t]*\^
+^[ \t]*If declarator-id:
+^[ \t]*Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^.*struct net_if __aligned\(32\)
+^[- \t]*\^

doc/api/api.rst

@@ -19,6 +19,7 @@ The Zephyr APIs are used the same way on all SoCs and boards.
    kernel_api.rst
    device.rst
    bluetooth.rst
+   networking.rst
    io_interfaces.rst
    power_management_api
    file_system

doc/api/networking.rst

@@ -0,0 +1,42 @@
+.. _networking_api:
+
+Networking API
+##############
+
+.. contents::
+   :depth: 1
+   :local:
+   :backlinks: top
+
+This is the full set of networking public APIs. Their exposure
+depends on relevant Kconfig options. For instance IPv6 related
+APIs will not be present if :option:`CONFIG_NET_IPV6` has not
+been selected.
+
+IPv4/IPv6 primitives and helpers
+*************************************
+
+.. doxygengroup:: ip_4_6
+   :project: Zephyr
+   :content-only:
+
+Network interface
+*****************
+
+.. doxygengroup:: net_if
+   :project: Zephyr
+   :content-only:
+
+Network Management
+******************
+
+.. doxygengroup:: net_mgmt
+   :project: Zephyr
+   :content-only:
+
+Application network context
+***************************
+
+.. doxygengroup:: net_context
+   :project: Zephyr
+   :content-only:

include/net/dhcpv4.h

@@ -11,6 +11,12 @@
 #ifndef __DHCPV4_H
 #define __DHCPV4_H
 
+/**
+ * @brief DHCPv4
+ * @defgroup dhcpv4 DHCPv4
+ * @{
+ */
+
 #include <misc/slist.h>
 #include <stdint.h>
 
@@ -35,4 +41,8 @@ enum net_dhcpv4_state {
  */
 void net_dhcpv4_start(struct net_if *iface);
 
+/**
+ * @}
+ */
+
 #endif /* __DHCPV4_H */

include/net/net_context.h

@@ -13,6 +13,12 @@
 #ifndef __NET_CONTEXT_H
 #define __NET_CONTEXT_H
 
+/**
+ * @brief Application network context
+ * @defgroup net_context Application network context
+ * @{
+ */
+
 #include <kernel.h>
 #include <atomic.h>
 
@@ -57,6 +63,7 @@ enum net_context_state {
 struct net_context;
 
 /**
+ * @typedef net_context_recv_cb_t
  * @brief Network data receive callback.
  *
  * @details The recv callback is called after a network data is
@@ -77,6 +84,7 @@ typedef void (*net_context_recv_cb_t)(struct net_context *context,
 				      void *user_data);
 
 /**
+ * @typedef net_context_send_cb_t
  * @brief Network data send callback.
  *
  * @details The send callback is called after a network data is
@@ -95,6 +103,7 @@ typedef void (*net_context_send_cb_t)(struct net_context *context,
 				      void *user_data);
 
 /**
+ * @typedef net_tcp_accept_cb_t
  * @brief Accept callback
  *
  * @details The accept callback is called after a successful
@@ -114,6 +123,7 @@ typedef void (*net_tcp_accept_cb_t)(struct net_context *new_context,
 				    void *user_data);
 
 /**
+ * @typedef net_context_connect_cb_t
  * @brief Connection callback.
  *
  * @details The connect callback is called after a connection is being
@@ -663,6 +673,13 @@ int net_context_recv(struct net_context *context,
 		     int32_t timeout,
 		     void *user_data);
 
+/**
+ * @typedef net_context_cb_t
+ * @brief Callback used while iterating over network contexts
+ *
+ * @param context A valid pointer on current network context
+ * @param user_data A valid pointer on some user data or NULL
+ */
 typedef void (*net_context_cb_t)(struct net_context *context, void *user_data);
 
 /**
@@ -678,4 +695,8 @@ void net_context_foreach(net_context_cb_t cb, void *user_data);
 }
 #endif
 
+/**
+ * @}
+ */
+
 #endif /* __NET_CONTEXT_H */

include/net/net_if.h

@@ -12,6 +12,12 @@
 #ifndef __NET_IF_H__
 #define __NET_IF_H__
 
+/**
+ * @brief Network Interface abstraction layer
+ * @defgroup net_if Network Interface abstraction layer
+ * @{
+ */
+
 #include <device.h>
 #include <misc/slist.h>
 
@@ -1076,6 +1082,13 @@ struct net_if *net_if_get_by_index(uint8_t index);
  */
 uint8_t net_if_get_by_iface(struct net_if *iface);
 
+/**
+ * @typedef net_if_cb_t
+ * @brief Callback used while iterating over network interfaces
+ *
+ * @param iface Pointer to current network interface
+ * @param user_data A valid pointer on some user data or NULL
+ */
 typedef void (*net_if_cb_t)(struct net_if *iface, void *user_data);
 
 /**
@@ -1157,4 +1170,8 @@ struct net_if_api {
 }
 #endif
 
+/**
+ * @}
+ */
+
 #endif /* __NET_IF_H__ */

include/net/net_ip.h

@@ -13,6 +13,12 @@
 #ifndef __NET_IP_H
 #define __NET_IP_H
 
+/**
+ * @brief IPv4/IPv6 primitives and helpers
+ * @defgroup ip_4_6 IPv4/IPv6 primitives and helpers
+ * @{
+ */
+
 #include <string.h>
 #include <stdint.h>
 #include <stdbool.h>
@@ -813,4 +819,9 @@ char *net_addr_ntop(sa_family_t family, const void *src,
 }
 #endif
 
+/**
+ * @}
+ */
+
+
 #endif /* __NET_IP_H */

include/net/net_mgmt.h

@@ -12,6 +12,12 @@
 #ifndef __NET_MGMT_H__
 #define __NET_MGMT_H__
 
+/**
+ * @brief Network Management
+ * @defgroup net_mgmt Network Management
+ * @{
+ */
+
 #include <misc/__assert.h>
 #include <net/net_core.h>
 
@@ -57,6 +63,7 @@ struct net_if;
 
 
 /**
+ * @typedef net_mgmt_request_handler_t
  * @brief Signature which all Net MGMT request handler need to follow
  * @param mgmt_request The exact request value the handler is being called
  *        through
@@ -171,4 +178,8 @@ void net_mgmt_event_init(void);
 #define net_mgmt_event_init(...)
 #endif /* CONFIG_NET_MGMT_EVENT */
 
+/**
+ * @}
+ */
+
 #endif /* __NET_MGMT_H__ */