net: Clarify UDP and TCP header getter and setter documentation

The net_tcp_get/set_hdr() and net_udp_get/set_hdr() documentation was not clear in corresponding header file. Clarify how the return value of the function is supposed to be used. Signed-off-by: Jukka Rissanen <[email protected]>
praveenmunagapati · Oct 23, 2017 · 363ccaf · 363ccaf
1 parent 898036d
commit 363ccaf
Show file tree

Hide file tree

Showing 2 changed files with 21 additions and 6 deletions.
diff --git a/include/net/udp.h b/include/net/udp.h
@@ -35,14 +35,16 @@ extern "C" {
  * @details The values in the returned header are in network byte order.
  * Note that you must access the UDP header values by the returned pointer,
  * the hdr parameter is just a placeholder for the header data and it might
- * not contain anything if header can fit properly in the first fragment in
+ * not contain anything if the header fits properly in the first fragment of
  * the network packet.
  *
  * @param pkt Network packet
  * @param hdr Where to place the header if it does not fit in first fragment
- * of the network packet.
+ * of the network packet. This might not be pupulated if UDP header fits in
+ * net_buf fragment.
  *
  * @return Return pointer to header or NULL if something went wrong.
+ *         Always use the returned pointer to access the UDP header.
  */
 struct net_udp_hdr *net_udp_get_hdr(struct net_pkt *pkt,
 				    struct net_udp_hdr *hdr);

diff --git a/subsys/net/ip/tcp.h b/subsys/net/ip/tcp.h
@@ -370,21 +370,34 @@ bool net_tcp_validate_seq(struct net_tcp *tcp, struct net_pkt *pkt);
 /**
  * @brief Get TCP packet header data from net_pkt. The array values are in
  * network byte order and other values are in host byte order.
+ * Note that you must access the TCP header values by the returned pointer,
+ * the hdr parameter is just a placeholder for the header data and it might
+ * not contain anything if the header fits properly in the first fragment of
+ * the network packet.
  *
  * @param pkt Network packet
- * @param hdr Where to place the header.
+ * @param hdr Where to place the header if it does not fit in first fragment
+ * of the network packet. This might not be pupulated if TCP header fits in
+ * net_buf fragment.
  *
  * @return Return pointer to header or NULL if something went wrong.
+ *         Always use the returned pointer to access the TCP header.
  */
 struct net_tcp_hdr *net_tcp_get_hdr(struct net_pkt *pkt,
 				    struct net_tcp_hdr *hdr);
 
 /**
- * @brief Set TCP packet header data in net_pkt. The array values are in
- * network byte order and other values are in host byte order.
+ * @brief Set TCP packet header data in net_pkt.
+ *
+ * @details  The values in the header must be in network byte order.
+ * This function is normally called after a call to net_tcp_get_hdr().
+ * The hdr parameter value should be the same that is returned by function
+ * net_tcp_get_hdr() call. Note that if the TCP header fits in first net_pkt
+ * fragment, then this function will not do anything as the returned value
+ * was pointing directly to net_pkt.
  *
  * @param pkt Network packet
- * @param hdr Header to be written
+ * @param hdr Header data pointer that was returned by net_tcp_get_hdr().
  *
  * @return Return hdr or NULL if error
  */