Merge pull request #8277 from miri64/doc/fix/must-not-may-not-wording

doc: Fix 'must not'/'may not' wording

core/include/lifo.h

@@ -40,16 +40,20 @@ int lifo_empty(int *array);
 /**
  * @brief               Initialize a lifo array.
  *
- * @param[in,out] array An array of size *n* + 1, may not be NULL.
+ * @pre `array != NULL`
+ *
+ * @param[in,out] array An array of size *n* + 1. Must not be `NULL`.
  * @param[in] n         Maximum integer value the lifo is able to store.
  */
 void lifo_init(int *array, int n);
 
 /**
  * @brief               Insert an element into the lifo
  *
+ * @pre `array != NULL`
+ *
  * @param[in,out] array An integer array of least *i* + 1 size that **does not
- *                      already contain *i***, may not be NULL.
+ *                      already contain *i***. Must not be `NULL`.
  * @param[in] i         The integer value to store, between 0 and the size of
  *                      the array - 1, must not be stored already.
  *
@@ -59,7 +63,9 @@ void lifo_insert(int *array, int i);
 /**
  * @brief           Extract the least recently inserted element from the lifo.
  *
- * @param[in] array An integer array, may not be NULL.
+ * @pre `array != NULL`
+ *
+ * @param[in] array An integer array. Must not be NULL.
  *
  * @return          -1, if the lifo is empty.
  * @return          the least recently inserted element, otherwise.

sys/include/net/gnrc/ipv6/nib/nc.h

@@ -247,7 +247,7 @@ void gnrc_ipv6_nib_nc_del(const ipv6_addr_t *ipv6, unsigned iface);
  *
  * @pre `ipv6 != NULL`
  *
- * @param[in] ipv6 A neighbor's IPv6 address. May not be NULL.
+ * @param[in] ipv6 A neighbor's IPv6 address. Must not be NULL.
  *
  * This function shall be called if an upper layer gets reachability
  * confirmation via its own means (e.g. a TCP connection build-up or

sys/include/net/gnrc/ipv6/nib/pl.h

@@ -50,7 +50,7 @@ typedef struct {
  * @param[in] iface         Interface @p pfx is valid on.
  * @param[in] pfx           The prefix. May not be a link-local prefix or a
  *                          multicast address and its first @p pfx_len bits
- *                          may not be 0.
+ *                          may not be 0. Must not be `NULL`.
  * @param[in] pfx_len       Length of @p pfx in bits.
  *                          Condition @p pfx_len > 0 must hold.
  * @param[in] valid_ltime   Lifetime (in ms) until prefix expires from now.

sys/include/net/gnrc/ndp.h

@@ -51,7 +51,7 @@ extern "C" {
  * @see [RFC 4861, section 4.3](https://tools.ietf.org/html/rfc4861#section-4.3)
  *
  * @param[in] tgt       The target address of the neighbor solicitation.
- *                      May not be NULL and **MUST NOT** be multicast.
+ *                      Must not be NULL or a multicast address.
  * @param[in] options   Options to append to the neighbor solicitation.
  *                      May be NULL for none.
  *
@@ -72,7 +72,7 @@ gnrc_pktsnip_t *gnrc_ndp_nbr_sol_build(const ipv6_addr_t *tgt,
  *                      in the neighbor solicitaton.
  *                      For and unsolicited advertisement, the address whose
  *                      link-layer address has changed.
- *                      May not be NULL and **MUST NOT** be multicast.
+ *                      Must not be NULL or a multicast address.
  * @param[in] flags     Neighbor advertisement flags:
  *                      - @ref NDP_NBR_ADV_FLAGS_R == 1 indicates, that the
  *                        sender is a router,
@@ -162,8 +162,8 @@ gnrc_pktsnip_t *gnrc_ndp_opt_build(uint8_t type, size_t size,
  *          hosts should silently ignore it in other NDP messages.
  *
  * @param[in] l2addr        A link-layer address of variable length.
- *                          May not be NULL.
- * @param[in] l2addr_len    Length of @p l2addr. May not be 0.
+ *                          Must not be NULL.
+ * @param[in] l2addr_len    Length of @p l2addr. Must not be 0.
  * @param[in] next          More options in the packet. NULL, if there are none.
  *
  * @return  The packet snip list of options, on success
@@ -185,8 +185,8 @@ gnrc_pktsnip_t *gnrc_ndp_opt_sl2a_build(const uint8_t *l2addr,
  *          in other NDP messages.
  *
  * @param[in] l2addr        A link-layer address of variable length.
- *                          May not be NULL.
- * @param[in] l2addr_len    Length of @p l2addr. May not be 0.
+ *                          Must not be NULL.
+ * @param[in] l2addr_len    Length of @p l2addr. Must not be 0.
  * @param[in] next          More options in the packet. NULL, if there are none.
  *
  * @return  The pkt snip list of options, on success
@@ -209,8 +209,8 @@ gnrc_pktsnip_t *gnrc_ndp_opt_tl2a_build(const uint8_t *l2addr,
  *          however, since nodes should silently ignore it in other NDP messages.
  *
  * @param[in] prefix        An IPv6 address or a prefix of an IPv6 address.
- *                          May not be NULL and must not be link-local or
- *                          multicast.
+ *                          Must not be NULL or be a link-local or
+ *                          multicast address.
  * @param[in] prefix_len    The length of @p prefix in bits. Must be between
  *                          0 and 128.
  * @param[in] valid_ltime   Length of time in seconds that @p prefix is valid.
@@ -258,11 +258,11 @@ gnrc_pktsnip_t *gnrc_ndp_opt_mtu_build(uint32_t mtu, gnrc_pktsnip_t *next);
  * @pre `(netif != NULL) && (dst != NULL)`
  *
  * @param[in] tgt       The target address of the neighbor solicitation.
- *                      May not be NULL and **MUST NOT** be multicast.
- * @param[in] netif     Interface to send over. May not be NULL.
+ *                      Must not be NULL or a multicast address.
+ * @param[in] netif     Interface to send over. Must not be NULL.
  * @param[in] src       Source address for the neighbor solicitation. Will be
  *                      chosen from the interface according to @p dst, if NULL.
- * @param[in] dst       Destination address for neighbor solicitation. May not
+ * @param[in] dst       Destination address for neighbor solicitation. Must not
  *                      be NULL.
  * @param[in] ext_opts  External options for the neighbor advertisement.
  *                      Leave NULL for none.
@@ -294,7 +294,7 @@ void gnrc_ndp_nbr_sol_send(const ipv6_addr_t *tgt, gnrc_netif_t *netif,
  *
  * @param[in] tgt           Target address for the neighbor advertisement. May
  *                          not be NULL and **MUST NOT** be multicast.
- * @param[in] netif         Interface to send over. May not be NULL.
+ * @param[in] netif         Interface to send over. Must not be NULL.
  * @param[in] dst           Destination address for neighbor advertisement. May
  *                          not be NULL. Is set to
  *                          @ref IPV6_ADDR_ALL_NODES_LINK_LOCAL when equal to
@@ -326,7 +326,7 @@ void gnrc_ndp_nbr_adv_send(const ipv6_addr_t *tgt, gnrc_netif_t *netif,
  *
  * @pre `(netif != NULL)`
  *
- * @param[in] netif Interface to send over. May not be NULL.
+ * @param[in] netif Interface to send over. Must not be NULL.
  * @param[in] dst   Destination for the router solicitation. ff02::2 if NULL.
  */
 void gnrc_ndp_rtr_sol_send(gnrc_netif_t *netif, const ipv6_addr_t *dst);
@@ -341,7 +341,7 @@ void gnrc_ndp_rtr_sol_send(gnrc_netif_t *netif, const ipv6_addr_t *dst);
  * dependent on external set-ups (e.g. if multihop prefix distribution is used).
  * Provide them via @p ext_opts
  *
- * @param[in] netif     Interface to send over. May not be NULL.
+ * @param[in] netif     Interface to send over. Must not be NULL.
  * @param[in] src       Source address for the router advertisement. May be
  *                      NULL to be determined by source address selection
  *                      (:: if @p netif has no address).

sys/include/net/gnrc/netif/internal.h

@@ -63,11 +63,11 @@ void gnrc_netif_release(gnrc_netif_t *netif);
  *      or loopback
  * @pre `(pfx_len > 0) && (pfx_len <= 128)`
  *
- * @param[in,out] netif the network interface. May not be NULL.
+ * @param[in,out] netif the network interface. Must not be NULL.
  * @param[in] addr      the address to add. If the address is already on the
  *                      interface the function will return 0, but @p flags
- *                      will be ignored. May not be NULL and may not be
- *                      link-local or multicast
+ *                      will be ignored. Must not be NULL or be a link-local or
+ *                      multicast address.
  * @param[in] pfx_len   length in bits of the prefix of @p addr
  * @param[in] flags     initial flags for the address.
  *                      - Setting the address' state to

sys/include/net/gnrc/pktqueue.h

@@ -42,7 +42,7 @@ typedef struct gnrc_pktqueue {
 /**
  * @brief       add @p node into @p queue.
  *
- * @param[in,out]   queue   the queue, may not be NULL
+ * @param[in,out]   queue   the queue. Must not be NULL
  * @param[in]       node    the node to add.
  */
 static inline void gnrc_pktqueue_add(gnrc_pktqueue_t **queue, gnrc_pktqueue_t *node)
@@ -53,7 +53,7 @@ static inline void gnrc_pktqueue_add(gnrc_pktqueue_t **queue, gnrc_pktqueue_t *n
 /**
  * @brief       remove @p node from @p queue
  *
- * @param[in]   queue   the queue, may not be NULL
+ * @param[in]   queue   the queue. Must not be NULL
  * @param[in]   node    the node to remove
  *
  * @return  @p node.
@@ -71,7 +71,7 @@ static inline gnrc_pktqueue_t *gnrc_pktqueue_remove(gnrc_pktqueue_t **queue, gnr
 /**
  * @brief remove the packet queue's head
  *
- * @param[in]  queue    the queue, may not be NULL
+ * @param[in]  queue    the queue. Must not be NULL
  *
  * @return              the old head
  */

sys/include/net/gnrc/priority_pktqueue.h

@@ -60,7 +60,7 @@ typedef priority_queue_t gnrc_priority_pktqueue_t;
  * @brief   Initialize a gnrc priority packet queue node object.
  *
  * @param[out] node
- *          pre-allocated gnrc_priority_pktqueue_node_t object, must not be NULL.
+ *          pre-allocated gnrc_priority_pktqueue_node_t object. Must not be NULL.
  * @param[in]  priority
  *          the priority of the gnrc packet snip
  * @param[in]  pkt
@@ -79,7 +79,7 @@ static inline void gnrc_priority_pktqueue_node_init(gnrc_priority_pktqueue_node_
  * @brief   Initialize a gnrc priority packet queue object.
  *
  * @param[out] queue
- *          pre-allocated gnrc_priority_pktqueue_t object, must not be NULL.
+ *          pre-allocated gnrc_priority_pktqueue_t object. Must not be NULL.
  */
 static inline void gnrc_priority_pktqueue_init(gnrc_priority_pktqueue_t *queue)
 {
@@ -92,22 +92,22 @@ static inline void gnrc_priority_pktqueue_init(gnrc_priority_pktqueue_t *queue)
  * @brief   Get the length information of a gnrc priority packet queue object.
  *
  * @param[in] queue
- *          pre-allocated gnrc_priority_pktqueue_t object, must not be NULL.
+ *          pre-allocated gnrc_priority_pktqueue_t object. Must not be NULL.
  * @return  the length of @p queue
  */
 uint32_t gnrc_priority_pktqueue_length(gnrc_priority_pktqueue_t *queue);
 
 /**
  * @brief flush the gnrc priority packet queue
  *
- * @param[out]  queue    the gnrc priority packet queue, must not be NULL
+ * @param[out]  queue    the gnrc priority packet queue. Must not be NULL
  */
 void gnrc_priority_pktqueue_flush(gnrc_priority_pktqueue_t *queue);
 
 /**
  * @brief Get first element and remove it from @p queue
  *
- * @param[out]  queue   the gnrc priority packet queue, may not be NULL
+ * @param[out]  queue   the gnrc priority packet queue. Must not be NULL
  *
  * @return              the old head
  */
@@ -116,7 +116,7 @@ gnrc_pktsnip_t *gnrc_priority_pktqueue_pop(gnrc_priority_pktqueue_t *queue);
 /**
  * @brief Get first element from @p queue without removing
  *
- * @param[in]  queue    the gnrc priority packet queue, may not be NULL
+ * @param[in]  queue    the gnrc priority packet queue. Must not be NULL
  *
  * @return              the head of @p queue
  */
@@ -125,7 +125,7 @@ gnrc_pktsnip_t *gnrc_priority_pktqueue_head(gnrc_priority_pktqueue_t *queue);
 /**
  * @brief       add @p node into @p queue based on its priority
  *
- * @param[in,out]   queue   the gnrc priority packet queue, must not be NULL
+ * @param[in,out]   queue   the gnrc priority packet queue. Must not be NULL
  * @param[in]       node    the node to add.
  */
 void gnrc_priority_pktqueue_push(gnrc_priority_pktqueue_t *queue,

sys/include/net/ndp.h

@@ -157,7 +157,7 @@ extern "C" {
 /**
  * @brief   Default for DupAddrDetectTransmits
  * @see     [RFC 4862, section 5.1](https://tools.ietf.org/html/rfc4862#section-5.1)
- * @note    May not be greater than 7.
+ * @note    Must not be greater than 7.
  */
 #define NDP_DAD_TRANSMIT_NUMOF      (1U)
 #define NDP_MAX_ANYCAST_MS_DELAY    (1000U)     /**< MAX_ANYCAST_DELAY_TIME (in ms) */

sys/include/net/sixlowpan.h

@@ -238,7 +238,7 @@ static inline bool sixlowpan_frag_is(sixlowpan_frag_t *hdr)
 /**
  * @brief   Checks if datagram is an IPHC datagram.
  *
- * @param[in] data  Data of a datagram, may not be NULL.
+ * @param[in] data  Data of a datagram. Must not be NULL.
  *
  * @return  true, if datagram is an IPHC datagram.
  * @return  false, if datagram is not an IPHC datagram.

sys/include/net/sixlowpan/nd.h

@@ -115,7 +115,7 @@ extern "C" {
 /**
  * @brief   Number of address registration retries
  *
- * @note    May not be greater than 7.
+ * @note    Must not be greater than 7.
  */
 #define SIXLOWPAN_ND_REG_TRANSMIT_NUMOF         (3U)
 /**

sys/include/net/sock/udp.h

@@ -299,16 +299,16 @@ typedef struct sock_udp sock_udp_t;
  * @param[out] sock     The resulting sock object.
  * @param[in] local     Local end point for the sock object.
  *                      May be NULL.
- *                      sock_udp_ep_t::port may not be 0 if `local != NULL`.
+ *                      sock_udp_ep_t::port must not be 0 if `local != NULL`.
  *                      sock_udp_ep_t::netif must either be
  *                      @ref SOCK_ADDR_ANY_NETIF or equal to
  *                      sock_udp_ep_t::netif of @p remote if `remote != NULL`.
  *                      If NULL @ref sock_udp_send() may bind implicitly.
  * @param[in] remote    Remote end point for the sock object.
  *                      May be `NULL` but then the `remote` parameter of
- *                      @ref sock_udp_send() may not be `NULL` and or it will
+ *                      @ref sock_udp_send() may not be `NULL` or it will
  *                      always error with return value -ENOTCONN.
- *                      sock_udp_ep_t::port may not be 0 if `remote != NULL`.
+ *                      sock_udp_ep_t::port must not be 0 if `remote != NULL`.
  *                      sock_udp_ep_t::netif must either be
  *                      @ref SOCK_ADDR_ANY_NETIF or equal to sock_udp_ep_t::netif
  *                      of @p local if `local != NULL`.

sys/net/gnrc/network_layer/ipv6/nib/_nib-arsm.h

@@ -41,11 +41,11 @@ extern "C" {
  * @pre `(netif != NULL) && (dst != NULL)`
  *
  * @param[in] tgt       The target address of the neighbor solicitation.
- *                      May not be NULL and **MUST NOT** be multicast.
- * @param[in] netif     Interface to send over. May not be NULL.
+ *                      Must not be NULL or a multicast address.
+ * @param[in] netif     Interface to send over. Must not be NULL.
  * @param[in] src       Source address for the neighbor solicitation. Will be
  *                      chosen from the interface according to @p dst, if NULL.
- * @param[in] dst       Destination address for neighbor solicitation. May not
+ * @param[in] dst       Destination address for neighbor solicitation. Must not
  *                      be NULL.
  */
 void _snd_ns(const ipv6_addr_t *tgt, gnrc_netif_t *netif,