mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2024-12-29 04:50:03 +01:00
Merge pull request #8277 from miri64/doc/fix/must-not-may-not-wording
doc: Fix 'must not'/'may not' wording
This commit is contained in:
commit
4013adcf65
@ -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.
|
||||
|
@ -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
|
||||
|
@ -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.
|
||||
|
@ -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).
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
*/
|
||||
|
@ -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,
|
||||
|
@ -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) */
|
||||
|
@ -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.
|
||||
|
@ -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)
|
||||
/**
|
||||
|
@ -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`.
|
||||
|
@ -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,
|
||||
|
@ -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.
|
||||
*
|
||||
|
Loading…
Reference in New Issue
Block a user