[API-NEXT,PATCHv2,1/3] api: packet: update doxygen for multi-segment push/pull operations

diff --git a/include/odp/api/spec/packet.h b/include/odp/api/spec/packet.h
index 9c63b5f..4fa5a73 100644
--- a/include/odp/api/spec/packet.h
+++ b/include/odp/api/spec/packet.h
@@ -294,9 +294,13 @@  void *odp_packet_tail(odp_packet_t pkt);
  * Push out packet head
  *
  * Increase packet data length by moving packet head into packet headroom.
- * Packet headroom is decreased with the same amount. The packet head may be
- * pushed out up to 'headroom' bytes. Packet is not modified if there's not
- * enough headroom space.
+ * Packet headroom is decreased by the same amount. If there is insufficient
+ * headroom available in the current segment the packet MAY be extended with
+ * additional segment(s) to accommodate the push request. Note that such
+ * extension may change the segmentation of the packet but does not affect
+ * the packet handle. As a result, the entire requested length may not be
+ * contiguously addressable from the returned data pointer. Use
+ * odp_packet_offset() to obtain this information if needed.
  *
  * odp_packet_xxx:
  * seg_len  += len
@@ -304,12 +308,11 @@  void *odp_packet_tail(odp_packet_t pkt);
  * headroom -= len
  * data     -= len
  *
- * Operation does not modify packet segmentation or move data. Handles and
- * pointers remain valid. User is responsible to update packet metadata
- * offsets when needed.
+ * Following this operation packet handles and pointers remain valid. User is
+ * responsible to update packet metadata offsets when needed.
  *
  * @param pkt  Packet handle
- * @param len  Number of bytes to push the head (0 ... headroom)
+ * @param len  Number of bytes to push the head (0 or more)
  *
  * @return The new data pointer
  * @retval NULL  Requested offset exceeds available headroom
@@ -322,9 +325,8 @@  void *odp_packet_push_head(odp_packet_t pkt, uint32_t len);
  * Pull in packet head
  *
  * Decrease packet data length by removing data from the head of the packet.
- * Packet headroom is increased with the same amount. Packet head may be pulled
- * in up to seg_len - 1 bytes (i.e. packet data pointer must stay in the
- * first segment). Packet is not modified if there's not enough data.
+ * Packet headroom is increased with the same amount. Packet is not modified
+ * if there's not enough data.
  *
  * odp_packet_xxx:
  * seg_len  -= len
@@ -332,9 +334,8 @@  void *odp_packet_push_head(odp_packet_t pkt, uint32_t len);
  * headroom += len
  * data     += len
  *
- * Operation does not modify packet segmentation or move data. Handles and
- * pointers remain valid. User is responsible to update packet metadata
- * offsets when needed.
+ * Following this operation packet handles and pointers remain valid. User is
+ * responsible to update packet metadata offsets when needed.
  *
  * @param pkt  Packet handle
  * @param len  Number of bytes to pull the head (0 ... seg_len - 1)
@@ -350,9 +351,15 @@  void *odp_packet_pull_head(odp_packet_t pkt, uint32_t len);
  * Push out packet tail
  *
  * Increase packet data length by moving packet tail into packet tailroom.
- * Packet tailroom is decreased with the same amount. The packet tail may be
- * pushed out up to 'tailroom' bytes. Packet is not modified if there's not
- * enough tailroom.
+ * Packet tailroom is decreased with the same amount. If the requested len
+ * exceeds the current tailroom, the packet MAY be extended with additional
+ * segment(s) to accommodate the push request. Note that such extension may
+ * change the segmentation of the packet but does not affect the packet
+ * handle. As a result, the entire requested length may not be contiguously
+ * addressable from the returned data pointer. Use odp_packet_offset() to
+ * obtain this information if needed.
+ *
+ * Packet is not modified if there's not enough tailroom.
  *
  * last_seg:
  * data_len += len
@@ -362,8 +369,7 @@  void *odp_packet_pull_head(odp_packet_t pkt, uint32_t len);
  * tail     += len
  * tailroom -= len
  *
- * Operation does not modify packet segmentation or move data. Handles,
- * pointers and offsets remain valid.
+ * Following this operation packet handles, pointers and offsets remain valid.
  *
  * @param pkt  Packet handle
  * @param len  Number of bytes to push the tail (0 ... tailroom)
@@ -379,9 +385,8 @@  void *odp_packet_push_tail(odp_packet_t pkt, uint32_t len);
  * Pull in packet tail
  *
  * Decrease packet data length by removing data from the tail of the packet.
- * Packet tailroom is increased with the same amount. Packet tail may be pulled
- * in up to last segment data_len - 1 bytes. (i.e. packet tail must stay in the
- * last segment). Packet is not modified if there's not enough data.
+ * Packet tailroom is increased with the same amount. Packet is not modified
+ * if there's not enough data.
  *
  * last_seg:
  * data_len -= len
@@ -391,9 +396,8 @@  void *odp_packet_push_tail(odp_packet_t pkt, uint32_t len);
  * tail     -= len
  * tailroom += len
  *
- * Operation does not modify packet segmentation or move data. Handles and
- * pointers remain valid. User is responsible to update packet metadata
- * offsets when needed.
+ * Following this operation packet handles and pointers remain valid. User is
+ * responsible to update packet metadata offsets when needed.
  *
  * @param pkt  Packet handle
  * @param len  Number of bytes to pull the tail (0 ... last_seg:data_len - 1)