Make lwIP compile with clang -Wdocumentation -> several documentation fixes

src/apps/httpd/httpd.c

@@ -1879,7 +1879,7 @@ http_continue(void *connection)
  * When data has been received in the correct state, try to parse it
  * as a HTTP request.
  *
- * @param p the received pbuf
+ * @param inp the received pbuf
  * @param hs the connection state
  * @param pcb the tcp_pcb which received this packet
  * @return ERR_OK if request was OK and hs has been initialized correctly
@@ -2211,7 +2211,7 @@ http_find_file(struct http_state *hs, const char *uri, int is_09)
  * @param is_09 1 if the request is HTTP/0.9 (no HTTP headers in response)
  * @param uri the HTTP header URI
  * @param tag_check enable SSI tag checking
- * @param uri_has_params != NULL if URI has parameters (separated by '?')
+ * @param params != NULL if URI has parameters (separated by '?')
  * @return ERR_OK if file was found and hs has been initialized correctly
  *         another err_t otherwise
  */

src/apps/mdns/mdns.c

@@ -1742,8 +1742,6 @@ mdns_handle_response(struct mdns_packet *pkt)
 /**
  * Receive input function for MDNS packets.
  * Handles both IPv4 and IPv6 UDP pcbs.
- *
- * @params see udp.h
  */
 static void
 mdns_recv(void *arg, struct udp_pcb *pcb, struct pbuf *p, const ip_addr_t *addr, u16_t port)

src/apps/snmp/snmp_asn1.c

@@ -288,7 +288,7 @@ snmp_asn1_enc_oid(struct snmp_pbuf_stream* pbuf_stream, const u32_t *oid, u16_t
 /**
  * Returns octet count for length.
  *
- * @param length
+ * @param length parameter length
  * @param octets_needed points to the return value
  */
 void
@@ -306,7 +306,7 @@ snmp_asn1_enc_length_cnt(u16_t length, u8_t *octets_needed)
 /**
  * Returns octet count for an u32_t.
  *
- * @param value
+ * @param value value to be encoded
  * @param octets_needed points to the return value
  *
  * @note ASN coded integers are _always_ signed. E.g. +0xFFFF is coded
@@ -332,7 +332,7 @@ snmp_asn1_enc_u32t_cnt(u32_t value, u16_t *octets_needed)
 /**
  * Returns octet count for an u64_t.
  *
- * @param value
+ * @param value value to be encoded
  * @param octets_needed points to the return value
  *
  * @note ASN coded integers are _always_ signed. E.g. +0xFFFF is coded
@@ -357,7 +357,7 @@ snmp_asn1_enc_u64t_cnt(const u32_t *value, u16_t *octets_needed)
 /**
  * Returns octet count for an s32_t.
  *
- * @param value
+ * @param value value to be encoded
  * @param octets_needed points to the return value
  *
  * @note ASN coded integers are _always_ signed.

src/apps/snmp/snmp_core.c

@@ -359,9 +359,9 @@ snmp_ip6_to_oid(const ip6_addr_t *ip, u32_t *oid)
 #if LWIP_IPV4 || LWIP_IPV6
 /**
  * Convert to InetAddressType+InetAddress+InetPortNumber
- * @param ip
- * @param port
- * @param oid
+ * @param ip IP address
+ * @param port Port
+ * @param oid OID
  * @return OID length
  */
 u8_t
@@ -378,8 +378,8 @@ snmp_ip_port_to_oid(const ip_addr_t *ip, u16_t port, u32_t *oid)
 
 /**
  * Convert to InetAddressType+InetAddress
- * @param ip
- * @param oid
+ * @param ip IP address
+ * @param oid OID
  * @return OID length
  */
 u8_t
@@ -412,9 +412,9 @@ snmp_ip_to_oid(const ip_addr_t *ip, u32_t *oid)
 
 /**
  * Convert from InetAddressType+InetAddress to ip_addr_t
- * @param oid
- * @param oid_len
- * @param ip
+ * @param oid OID
+ * @param oid_len OID length
+ * @param ip IP address
  * @return Parsed OID length
  */
 u8_t
@@ -487,10 +487,10 @@ snmp_oid_to_ip(const u32_t *oid, u8_t oid_len, ip_addr_t *ip)
 
 /**
  * Convert from InetAddressType+InetAddress+InetPortNumber to ip_addr_t and u16_t
- * @param oid
- * @param oid_len
- * @param ip
- * @param port
+ * @param oid OID
+ * @param oid_len OID length
+ * @param ip IP address
+ * @param port Port
  * @return Parsed OID length
  */
 u8_t
@@ -520,10 +520,10 @@ snmp_oid_to_ip_port(const u32_t *oid, u8_t oid_len, ip_addr_t *ip, u16_t *port)
 #endif /* LWIP_IPV4 || LWIP_IPV6 */
 
 /**
- * Assign an OID to \struct snmp_obj_id
- * @param target
- * @param oid
- * @param oid_len
+ * Assign an OID to struct snmp_obj_id
+ * @param target Assignment target 
+ * @param oid OID
+ * @param oid_len OID length
  */
 void
 snmp_oid_assign(struct snmp_obj_id* target, const u32_t *oid, u8_t oid_len)
@@ -538,10 +538,10 @@ snmp_oid_assign(struct snmp_obj_id* target, const u32_t *oid, u8_t oid_len)
 }
 
 /**
- * Prefix an OID to OID in \struct snmp_obj_id
- * @param target
- * @param oid
- * @param oid_len
+ * Prefix an OID to OID in struct snmp_obj_id
+ * @param target Assignment target to prefix
+ * @param oid OID
+ * @param oid_len OID length
  */
 void
 snmp_oid_prefix(struct snmp_obj_id* target, const u32_t *oid, u8_t oid_len)
@@ -561,12 +561,12 @@ snmp_oid_prefix(struct snmp_obj_id* target, const u32_t *oid, u8_t oid_len)
 }
 
 /**
- * Combine two OIDs into \struct snmp_obj_id
- * @param target
- * @param oid1
- * @param oid1_len
- * @param oid2
- * @param oid2_len
+ * Combine two OIDs into struct snmp_obj_id
+ * @param target Assignmet target
+ * @param oid1 OID 1
+ * @param oid1_len OID 1 length
+ * @param oid2 OID 2
+ * @param oid2_len OID 2 length
  */
 void
 snmp_oid_combine(struct snmp_obj_id* target, const u32_t *oid1, u8_t oid1_len, const u32_t *oid2, u8_t oid2_len)
@@ -576,10 +576,10 @@ snmp_oid_combine(struct snmp_obj_id* target, const u32_t *oid1, u8_t oid1_len, c
 }
 
 /**
- * Append OIDs to \struct snmp_obj_id
- * @param target
- * @param oid
- * @param oid_len
+ * Append OIDs to struct snmp_obj_id
+ * @param target Assignment target to append to
+ * @param oid OID
+ * @param oid_len OID length
  */
 void
 snmp_oid_append(struct snmp_obj_id* target, const u32_t *oid, u8_t oid_len)
@@ -594,11 +594,11 @@ snmp_oid_append(struct snmp_obj_id* target, const u32_t *oid, u8_t oid_len)
 
 /**
  * Compare two OIDs
- * @param oid1
- * @param oid1_len
- * @param oid2
- * @param oid2_len
- * @return
+ * @param oid1 OID 1
+ * @param oid1_len OID 1 length
+ * @param oid2 OID 2
+ * @param oid2_len OID 2 length
+ * @return -1: OID1<OID2  1: OID1 >OID2 0: equal
  */
 s8_t
 snmp_oid_compare(const u32_t *oid1, u8_t oid1_len, const u32_t *oid2, u8_t oid2_len)
@@ -635,11 +635,11 @@ snmp_oid_compare(const u32_t *oid1, u8_t oid1_len, const u32_t *oid2, u8_t oid2_
 
 /**
  * Check of two OIDs are equal
- * @param oid1
- * @param oid1_len
- * @param oid2
- * @param oid2_len
- * @return
+ * @param oid1 OID 1
+ * @param oid1_len OID 1 length
+ * @param oid2 OID 2
+ * @param oid2_len OID 2 length
+ * @return 1: equal 0: non-equal
  */
 u8_t
 snmp_oid_equal(const u32_t *oid1, u8_t oid1_len, const u32_t *oid2, u8_t oid2_len)
@@ -649,7 +649,7 @@ snmp_oid_equal(const u32_t *oid1, u8_t oid1_len, const u32_t *oid2, u8_t oid2_le
 
 /**
  * Convert netif to interface index
- * @param netif
+ * @param netif netif
  * @return index
  */
 u8_t

src/apps/snmp/snmp_mib2_ip.c

@@ -146,7 +146,7 @@ ip_get_value(struct snmp_node_instance* instance, void* value)
 /**
  * Test ip object value before setting.
  *
- * @param od is the object definition
+ * @param instance node instance
  * @param len return value space (in bytes)
  * @param value points to (varbind) space to copy value from.
  *

src/apps/snmp/snmp_msg.c

@@ -323,7 +323,7 @@ snmp_process_varbind(struct snmp_request *request, struct snmp_varbind *vb, u8_t
 /**
  * Service an internal or external event for SNMP GET.
  *
- * @param msg_ps points to the associated message process state
+ * @param request points to the associated message process state
  */
 static err_t
 snmp_process_get_request(struct snmp_request *request)
@@ -359,7 +359,7 @@ snmp_process_get_request(struct snmp_request *request)
 /**
  * Service an internal or external event for SNMP GET.
  *
- * @param msg_ps points to the associated message process state
+ * @param request points to the associated message process state
  */
 static err_t
 snmp_process_getnext_request(struct snmp_request *request)
@@ -395,7 +395,7 @@ snmp_process_getnext_request(struct snmp_request *request)
 /**
  * Service an internal or external event for SNMP GETBULKT.
  *
- * @param msg_ps points to the associated message process state
+ * @param request points to the associated message process state
  */
 static err_t
 snmp_process_getbulk_request(struct snmp_request *request)
@@ -493,7 +493,7 @@ snmp_process_getbulk_request(struct snmp_request *request)
 /**
  * Service an internal or external event for SNMP SET.
  *
- * @param msg_ps points to the associated message process state
+ * @param request points to the associated message process state
  */
 static err_t
 snmp_process_set_request(struct snmp_request *request)

src/apps/snmp/snmp_traps.c

@@ -297,8 +297,8 @@ snmp_trap_varbind_sum(struct snmp_msg_trap *trap, struct snmp_varbind *varbinds)
  * Sums trap header field lengths from tail to head and
  * returns trap_header_lengths for second encoding pass.
  *
+ * @param trap Trap message
  * @param vb_len varbind-list length
- * @param thl points to returned header lengths
  * @return the required length for encoding the trap header
  */
 static u16_t