diff --git a/core/include/lifo.h b/core/include/lifo.h index d6c9b8d9e3ca532d15985d1d2bc886aaed0c3ee8..39e93f158d36bee387141bf7ddf0ecbdc3bd579d 100644 --- a/core/include/lifo.h +++ b/core/include/lifo.h @@ -40,7 +40,9 @@ 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); @@ -48,8 +50,10 @@ 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. diff --git a/sys/include/net/gnrc/ipv6/nib/nc.h b/sys/include/net/gnrc/ipv6/nib/nc.h index 31414229832822a449e31a289b1bcc8ef371ee76..c7182e36bb29475bf2ae001d1477ce35815b9de2 100644 --- a/sys/include/net/gnrc/ipv6/nib/nc.h +++ b/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 diff --git a/sys/include/net/gnrc/ipv6/nib/pl.h b/sys/include/net/gnrc/ipv6/nib/pl.h index c5cbdae0434c2c3ef1d7bf0ce76d48be0ff28f46..88fbeda7f9232cd3ab9f463d3b82ec2f7c7140b2 100644 --- a/sys/include/net/gnrc/ipv6/nib/pl.h +++ b/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. diff --git a/sys/include/net/gnrc/ndp.h b/sys/include/net/gnrc/ndp.h index 64916e02361dafb3d9904ea2d6d8a25c637856bf..660f47646f92e0a2ce5b4d25733b173fb4d83a48 100644 --- a/sys/include/net/gnrc/ndp.h +++ b/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). diff --git a/sys/include/net/gnrc/netif/internal.h b/sys/include/net/gnrc/netif/internal.h index d673e497c9932c5a71932ee039d74945ac77f294..8e071a4474fb6779f76dc807edc9c8cca075d8c8 100644 --- a/sys/include/net/gnrc/netif/internal.h +++ b/sys/include/net/gnrc/netif/internal.h @@ -59,11 +59,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 diff --git a/sys/include/net/gnrc/pktqueue.h b/sys/include/net/gnrc/pktqueue.h index fa6efe9f04924847c980ce207bf5420962b06133..ccbd850cf7e2597162a1e1e4483969a72876983b 100644 --- a/sys/include/net/gnrc/pktqueue.h +++ b/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 */ diff --git a/sys/include/net/gnrc/priority_pktqueue.h b/sys/include/net/gnrc/priority_pktqueue.h index d60e6fc381c28ae3b5074acc7e2688dcf68a741f..e3cb0f2607c41805b5046e9dd764dbe0fc30aecb 100644 --- a/sys/include/net/gnrc/priority_pktqueue.h +++ b/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,7 +92,7 @@ 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); @@ -100,14 +100,14 @@ 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, diff --git a/sys/include/net/ndp.h b/sys/include/net/ndp.h index 84c8404aa88f88b7a831ff1f772381ba37a19752..9f2f5359a7cf50e2fd5c09688bfc46d545235271 100644 --- a/sys/include/net/ndp.h +++ b/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) */ diff --git a/sys/include/net/sixlowpan.h b/sys/include/net/sixlowpan.h index 236c2096fd60f9cd705711ab610dad8e9ffd7ca9..083f4adb5669476adfe264ec2b52cf61f8d9526b 100644 --- a/sys/include/net/sixlowpan.h +++ b/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. diff --git a/sys/include/net/sixlowpan/nd.h b/sys/include/net/sixlowpan/nd.h index 2c631e42eb46fcf1d3520c4285f0ea20c2d49b6b..026165a108fd4b61a6506d20af8717c9fb511909 100644 --- a/sys/include/net/sixlowpan/nd.h +++ b/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) /** diff --git a/sys/include/net/sock/udp.h b/sys/include/net/sock/udp.h index 82136a1552e6827b8bbbd48de82e4ea1c2695e3c..0b9e30e81028e958b334d422a74882e6d2f31b16 100644 --- a/sys/include/net/sock/udp.h +++ b/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`. diff --git a/sys/net/gnrc/network_layer/ipv6/nib/_nib-arsm.h b/sys/net/gnrc/network_layer/ipv6/nib/_nib-arsm.h index 12e8286dd1e2e4583c0109bac28c09f5bc045b8b..abfdb8f263cb8a0374b3a6e944b6c95d74ca26fe 100644 --- a/sys/net/gnrc/network_layer/ipv6/nib/_nib-arsm.h +++ b/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, diff --git a/sys/net/gnrc/network_layer/ipv6/nib/_nib-internal.h b/sys/net/gnrc/network_layer/ipv6/nib/_nib-internal.h index a17a11c099b6ca9c1045480c3d21a4a08dbf879b..78b6d1a88d776f6d4a39b9b21f1242fc1c878651 100644 --- a/sys/net/gnrc/network_layer/ipv6/nib/_nib-internal.h +++ b/sys/net/gnrc/network_layer/ipv6/nib/_nib-internal.h @@ -334,7 +334,7 @@ _nib_onl_entry_t *_nib_onl_iter(const _nib_onl_entry_t *last); * * @pre `(addr != NULL)` * - * @param[in] addr The address of a node. May not be NULL. + * @param[in] addr The address of a node. Must not be NULL. * @param[in] iface The interface to the node. May be 0 for any interface. * * @return The NIB entry for node with @p addr and @p iface on success. @@ -395,7 +395,7 @@ void _nib_nc_set_reachable(_nib_onl_entry_t *node); * * @pre `addr != NULL` * - * @param[in] addr The address of a node. May not be NULL. + * @param[in] addr The address of a node. Must not be NULL. * * @return The NIB entry for the new DAD table entry on success. * @return NULL, if there is no space left. @@ -425,9 +425,9 @@ static inline void _nib_dad_remove(_nib_onl_entry_t *node) /** * @brief Creates or gets an existing default router list entry by address * - * @pre `(router_addr != NULL)` + * @pre `(addr != NULL)` * - * @param[in] addr An IPv6 address. May not be NULL. + * @param[in] addr An IPv6 address. Must not be NULL. * *May also be a global address!* * @param[in] iface The interface to the router. * @@ -435,7 +435,7 @@ static inline void _nib_dad_remove(_nib_onl_entry_t *node) * of _nib_dr_entry_t::next_hop set to @p router_addr. * @return NULL, if no space is left. */ -_nib_dr_entry_t *_nib_drl_add(const ipv6_addr_t *router_addr, unsigned iface); +_nib_dr_entry_t *_nib_drl_add(const ipv6_addr_t *addr, unsigned iface); /** * @brief Removes a default router list entry @@ -460,7 +460,7 @@ _nib_dr_entry_t *_nib_drl_iter(const _nib_dr_entry_t *last); * * @pre `(router_addr != NULL)` * - * @param[in] router_addr The address of a default router. May not be NULL. + * @param[in] router_addr The address of a default router. Must not be NULL. * @param[in] iface The interface to the node. May be 0 for any * interface. * @@ -499,7 +499,7 @@ _nib_dr_entry_t *_nib_drl_get_dr(void); * list). *May also be a global address!* * @param[in] iface The interface to @p next_hop. * @param[in] pfx The IPv6 prefix or address of the destination. - * May not be NULL or unspecified address. Use + * Must not be NULL or unspecified address. Use * @ref _nib_drl_add() for default route destinations. * @param[in] pfx_len The length in bits of @p pfx in bits. * @@ -545,7 +545,7 @@ bool _nib_offl_is_entry(const _nib_offl_entry_t *entry); * list). *May also be a global address!* * @param[in] iface The interface to the destination. * @param[in] pfx The IPv6 prefix or address of the destination. - * May not be NULL or unspecified address. Use + * Must not be NULL or unspecified address. Use * @ref _nib_drl_add() for default route destinations. * @param[in] pfx_len The length in bits of @p pfx in bits. * @param[in] mode [NIB-mode](_nib_onl_entry_t::mode). @@ -585,7 +585,7 @@ static inline void _nib_offl_remove(_nib_offl_entry_t *nib_offl, uint8_t mode) * @pre `(next_hop != NULL)` * @pre `(dst != NULL)` * - * @param[in] next_hop Next hop to the destination. May not be NULL. + * @param[in] next_hop Next hop to the destination. Must not be NULL. * *May also be a global address!* * @param[in] iface The interface to the destination. * @@ -627,7 +627,7 @@ static inline void _nib_dc_remove(_nib_offl_entry_t *nib_offl) * * @param[in] iface The interface to the prefix is added to. * @param[in] pfx The IPv6 prefix or address of the destination. - * May not be NULL or unspecified address. Use + * Must not be NULL or unspecified address. Use * @ref _nib_drl_add() for default route destinations. * @param[in] pfx_len The length in bits of @p pfx in bits. * @param[in] valid_ltime Valid lifetime in microseconds. `UINT32_MAX` for @@ -661,11 +661,11 @@ void _nib_pl_remove(_nib_offl_entry_t *nib_offl); * @pre `(next_hop != NULL)` * @pre `(pfx != NULL) && (pfx != "::") && (pfx_len != 0) && (pfx_len <= 128)` * - * @param[in] next_hop Next hop to the destination. May not be NULL. + * @param[in] next_hop Next hop to the destination. Must not be NULL. * *May also be a global address!* * @param[in] iface The interface to the destination. * @param[in] pfx The IPv6 prefix or address of the destination. - * May not be NULL or unspecified address. Use + * Must not be NULL or unspecified address. Use * @ref _nib_drl_add() for default route destinations. * @param[in] pfx_len The length in bits of @p pfx in bits. *