Fix and simplify newlines in doxygen documentation

Replace '\n' with '<br>', as this allows doxygen to understand reference names followed by newline. For some cases just drop the newline if it's not required. Doxygen 1.8.15 doesn't like if the name of reference is followed by anything else than (selected?) punctuation or whitespace. bug #56004
2026-09-22 00:33:46 +08:00 · 2019-03-26 17:34:01 +01:00
parent c594599350
commit ec11b289cb
26 changed files with 89 additions and 88 deletions
--- a/src/include/lwip/altcp.h
+++ b/src/include/lwip/altcp.h
@@ -1,6 +1,6 @@
 /**
 * @file
- * Application layered TCP connection API (to be used from TCPIP thread)\n
+ * Application layered TCP connection API (to be used from TCPIP thread)
 *
 * This file contains the generic API.
 * For more details see @ref altcp_api.
--- a/src/include/lwip/altcp_tcp.h
+++ b/src/include/lwip/altcp_tcp.h
@@ -1,6 +1,6 @@
 /**
 * @file
- * Application layered TCP connection API (to be used from TCPIP thread)\n
+ * Application layered TCP connection API (to be used from TCPIP thread)<br>
 * This interface mimics the tcp callback API to the application while preventing
 * direct linking (much like virtual functions).
 * This way, an application can make use of other application layer protocols
--- a/src/include/lwip/altcp_tls.h
+++ b/src/include/lwip/altcp_tls.h
@@ -123,7 +123,7 @@ struct altcp_pcb *altcp_tls_new(struct altcp_tls_config *config, u8_t ip_type);
 /** @ingroup altcp_tls
 * Create new ALTCP_TLS layer pcb and its inner tcp pcb.
 * Same as @ref altcp_tls_new but this allocator function fits to
- * @ref altcp_allocator_t / @ref altcp_new.\n
+ * @ref altcp_allocator_t / @ref altcp_new.<br>
 'arg' must contain a struct altcp_tls_config *.
 */
 struct altcp_pcb *altcp_tls_alloc(void *arg, u8_t ip_type);
--- a/src/include/lwip/arch.h
+++ b/src/include/lwip/arch.h
@@ -72,7 +72,7 @@
 #define LWIP_RAND() ((u32_t)rand())
 #endif

-/** Platform specific diagnostic output.\n
+/** Platform specific diagnostic output.<br>
 * Note the default implementation pulls in printf, which may
 * in turn pull in a lot of standard libary code. In resource-constrained
 * systems, this should be defined to something less resource-consuming.
@@ -83,7 +83,7 @@
 #include <stdlib.h>
 #endif

-/** Platform specific assertion handling.\n
+/** Platform specific assertion handling.<br>
 * Note the default implementation pulls in printf, fflush and abort, which may
 * in turn pull in a lot of standard libary code. In resource-constrained
 * systems, this should be defined to something less resource-consuming.
@@ -261,10 +261,10 @@ typedef int ssize_t;
 * its start address using LWIP_MEM_ALIGN.
 * You can declare your own version here e.g. to enforce alignment without adding
 * trailing padding bytes (see LWIP_MEM_ALIGN_BUFFER) or your own section placement
- * requirements.\n
- * e.g. if you use gcc and need 32 bit alignment:\n
- * \#define LWIP_DECLARE_MEMORY_ALIGNED(variable_name, size) u8_t variable_name[size] \_\_attribute\_\_((aligned(4)))\n
- * or more portable:\n
+ * requirements.<br>
+ * e.g. if you use gcc and need 32 bit alignment:<br>
+ * \#define LWIP_DECLARE_MEMORY_ALIGNED(variable_name, size) u8_t variable_name[size] \_\_attribute\_\_((aligned(4)))<br>
+ * or more portable:<br>
 * \#define LWIP_DECLARE_MEMORY_ALIGNED(variable_name, size) u32_t variable_name[(size + sizeof(u32_t) - 1) / sizeof(u32_t)]
 */
 #ifndef LWIP_DECLARE_MEMORY_ALIGNED
@@ -299,8 +299,8 @@ extern "C" {
 #endif

 /** Packed structs support.
-  * Placed BEFORE declaration of a packed struct.\n
-  * For examples of packed struct declarations, see include/lwip/prot/ subfolder.\n
+  * Placed BEFORE declaration of a packed struct.<br>
+  * For examples of packed struct declarations, see include/lwip/prot/ subfolder.<br>
  * A port to GCC/clang is included in lwIP, if you use these compilers there is nothing to do here.
  */
 #ifndef PACK_STRUCT_BEGIN
@@ -308,8 +308,8 @@ extern "C" {
 #endif /* PACK_STRUCT_BEGIN */

 /** Packed structs support.
-  * Placed AFTER declaration of a packed struct.\n
-  * For examples of packed struct declarations, see include/lwip/prot/ subfolder.\n
+  * Placed AFTER declaration of a packed struct.<br>
+  * For examples of packed struct declarations, see include/lwip/prot/ subfolder.<br>
  * A port to GCC/clang is included in lwIP, if you use these compilers there is nothing to do here.
  */
 #ifndef PACK_STRUCT_END
@@ -317,8 +317,8 @@ extern "C" {
 #endif /* PACK_STRUCT_END */

 /** Packed structs support.
-  * Placed between end of declaration of a packed struct and trailing semicolon.\n
-  * For examples of packed struct declarations, see include/lwip/prot/ subfolder.\n
+  * Placed between end of declaration of a packed struct and trailing semicolon.<br>
+  * For examples of packed struct declarations, see include/lwip/prot/ subfolder.<br>
  * A port to GCC/clang is included in lwIP, if you use these compilers there is nothing to do here.
  */
 #ifndef PACK_STRUCT_STRUCT
@@ -330,8 +330,8 @@ extern "C" {
 #endif /* PACK_STRUCT_STRUCT */

 /** Packed structs support.
-  * Wraps u32_t and u16_t members.\n
-  * For examples of packed struct declarations, see include/lwip/prot/ subfolder.\n
+  * Wraps u32_t and u16_t members.<br>
+  * For examples of packed struct declarations, see include/lwip/prot/ subfolder.<br>
  * A port to GCC/clang is included in lwIP, if you use these compilers there is nothing to do here.
  */
 #ifndef PACK_STRUCT_FIELD
@@ -339,8 +339,8 @@ extern "C" {
 #endif /* PACK_STRUCT_FIELD */

 /** Packed structs support.
-  * Wraps u8_t members, where some compilers warn that packing is not necessary.\n
-  * For examples of packed struct declarations, see include/lwip/prot/ subfolder.\n
+  * Wraps u8_t members, where some compilers warn that packing is not necessary.<br>
+  * For examples of packed struct declarations, see include/lwip/prot/ subfolder.<br>
  * A port to GCC/clang is included in lwIP, if you use these compilers there is nothing to do here.
  */
 #ifndef PACK_STRUCT_FLD_8
@@ -348,20 +348,20 @@ extern "C" {
 #endif /* PACK_STRUCT_FLD_8 */

 /** Packed structs support.
-  * Wraps members that are packed structs themselves, where some compilers warn that packing is not necessary.\n
-  * For examples of packed struct declarations, see include/lwip/prot/ subfolder.\n
+  * Wraps members that are packed structs themselves, where some compilers warn that packing is not necessary.<br>
+  * For examples of packed struct declarations, see include/lwip/prot/ subfolder.<br>
  * A port to GCC/clang is included in lwIP, if you use these compilers there is nothing to do here.
  */
 #ifndef PACK_STRUCT_FLD_S
 #define PACK_STRUCT_FLD_S(x) PACK_STRUCT_FIELD(x)
 #endif /* PACK_STRUCT_FLD_S */

-/** PACK_STRUCT_USE_INCLUDES==1: Packed structs support using \#include files before and after struct to be packed.\n
- * The file included BEFORE the struct is "arch/bpstruct.h".\n
- * The file included AFTER the struct is "arch/epstruct.h".\n
+/** PACK_STRUCT_USE_INCLUDES==1: Packed structs support using \#include files before and after struct to be packed.<br>
+ * The file included BEFORE the struct is "arch/bpstruct.h".<br>
+ * The file included AFTER the struct is "arch/epstruct.h".<br>
 * This can be used to implement struct packing on MS Visual C compilers, see
 * the Win32 port in the lwIP/contrib subdir for reference.
- * For examples of packed struct declarations, see include/lwip/prot/ subfolder.\n
+ * For examples of packed struct declarations, see include/lwip/prot/ subfolder.<br>
 * A port to GCC/clang is included in lwIP, if you use these compilers there is nothing to do here.
 */
 #ifdef __DOXYGEN__
--- a/src/include/lwip/netif.h
+++ b/src/include/lwip/netif.h
@@ -583,8 +583,8 @@ typedef u16_t netif_nsc_reason_t;
 #define LWIP_NSC_NETIF_REMOVED            0x0002
 /** link changed */
 #define LWIP_NSC_LINK_CHANGED             0x0004
-/** netif administrative status changed.\n
-  * up is called AFTER netif is set up.\n
+/** netif administrative status changed.<br>
+  * up is called AFTER netif is set up.<br>
  * down is called BEFORE the netif is actually set down. */
 #define LWIP_NSC_STATUS_CHANGED           0x0008
 /** IPv4 address has changed */
--- a/src/include/lwip/opt.h
+++ b/src/include/lwip/opt.h
@@ -2807,16 +2807,16 @@
 * the standardized ISN generation algorithm from RFC 6528 (see contrib/adons/tcp_isn),
 * or any other desired algorithm as a replacement.
 * Called from tcp_connect() and tcp_listen_input() when an ISN is needed for
- * a new TCP connection, if TCP support (@ref LWIP_TCP) is enabled.\n
+ * a new TCP connection, if TCP support (@ref LWIP_TCP) is enabled.<br>
 * Signature:\code{.c}
 * u32_t my_hook_tcp_isn(const ip_addr_t* local_ip, u16_t local_port, const ip_addr_t* remote_ip, u16_t remote_port);
 * \endcode
- * - it may be necessary to use "struct ip_addr" (ip4_addr, ip6_addr) instead of "ip_addr_t" in function declarations\n
+ * - it may be necessary to use "struct ip_addr" (ip4_addr, ip6_addr) instead of "ip_addr_t" in function declarations<br>
 * Arguments:
 * - local_ip: pointer to the local IP address of the connection
 * - local_port: local port number of the connection (host-byte order)
 * - remote_ip: pointer to the remote IP address of the connection
- * - remote_port: remote port number of the connection (host-byte order)\n
+ * - remote_port: remote port number of the connection (host-byte order)<br>
 * Return value:
 * - the 32-bit Initial Sequence Number to use for the new TCP connection.
 */
@@ -3075,16 +3075,16 @@
 * LWIP_HOOK_VLAN_SET:
 * Hook can be used to set prio_vid field of vlan_hdr. If you need to store data
 * on per-netif basis to implement this callback, see @ref netif_cd.
- * Called from ethernet_output() if VLAN support (@ref ETHARP_SUPPORT_VLAN) is enabled.\n
+ * Called from ethernet_output() if VLAN support (@ref ETHARP_SUPPORT_VLAN) is enabled.<br>
 * Signature:\code{.c}
- *   s32_t my_hook_vlan_set(struct netif* netif, struct pbuf* pbuf, const struct eth_addr* src, const struct eth_addr* dst, u16_t eth_type);\n
+ *   s32_t my_hook_vlan_set(struct netif* netif, struct pbuf* pbuf, const struct eth_addr* src, const struct eth_addr* dst, u16_t eth_type);
 * \endcode
 * Arguments:
 * - netif: struct netif that the packet will be sent through
 * - p: struct pbuf packet to be sent
 * - src: source eth address
 * - dst: destination eth address
- * - eth_type: ethernet type to packet to be sent\n
+ * - eth_type: ethernet type to packet to be sent<br>
 *
 *
 * Return values:
--- a/src/include/lwip/priv/altcp_priv.h
+++ b/src/include/lwip/priv/altcp_priv.h
@@ -1,6 +1,6 @@
 /**
 * @file
- * Application layered TCP connection API (to be used from TCPIP thread)\n
+ * Application layered TCP connection API (to be used from TCPIP thread)<br>
 * This interface mimics the tcp callback API to the application while preventing
 * direct linking (much like virtual functions).
 * This way, an application can make use of other application layer protocols
--- a/src/include/lwip/raw.h
+++ b/src/include/lwip/raw.h
@@ -1,6 +1,6 @@
 /**
 * @file
- * raw API (to be used from TCPIP thread)\n
+ * raw API (to be used from TCPIP thread)<br>
 * See also @ref raw_raw
 */

--- a/src/include/lwip/tcp.h
+++ b/src/include/lwip/tcp.h
@@ -1,6 +1,6 @@
 /**
 * @file
- * TCP API (to be used from TCPIP thread)\n
+ * TCP API (to be used from TCPIP thread)<br>
 * See also @ref tcp_raw
 */

--- a/src/include/lwip/tcpbase.h
+++ b/src/include/lwip/tcpbase.h
@@ -1,6 +1,6 @@
 /**
 * @file
- * Base TCP API definitions shared by TCP and ALTCP\n
+ * Base TCP API definitions shared by TCP and ALTCP<br>
 * See also @ref tcp_raw
 */

--- a/src/include/lwip/udp.h
+++ b/src/include/lwip/udp.h
@@ -1,6 +1,6 @@
 /**
 * @file
- * UDP API (to be used from TCPIP thread)\n
+ * UDP API (to be used from TCPIP thread)<br>
 * See also @ref udp_raw
 */