RIOT-OS/RIOT
RIOT-OS/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2024-12-29 04:50:03 +01:00
Code Releases Activity

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

Browse Source 
I applied the following terminology and changed the wording in the doc
accordingly:

* must not: If the parameter is of the value it *must not* be it either
  hits an assert or crashes the system.
* may not: The value can be that value, but the function will return an
  error.
This commit is contained in:
Martine Lenders 2017-12-19 09:00:09 +01:00
parent 3a572d82cd
commit 2e93ba1c50
No known key found for this signature in database
GPG Key ID: 8E97A9FE55F25D62
13 changed files with 59 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
core/include/lifo.h
View File

@ -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.

2
sys/include/net/gnrc/ipv6/nib/nc.h
View File

@ -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

2
sys/include/net/gnrc/ipv6/nib/pl.h
View File

@ -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.

28
sys/include/net/gnrc/ndp.h
View File

@ -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).

6
sys/include/net/gnrc/netif/internal.h
View File

@ -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

6
sys/include/net/gnrc/pktqueue.h
View File

@ -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
*/

14
sys/include/net/gnrc/priority_pktqueue.h
View File

@ -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,

2
sys/include/net/ndp.h
View File

@ -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) */

2
sys/include/net/sixlowpan.h
View File

@ -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.

2
sys/include/net/sixlowpan/nd.h
View File

@ -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)
/**

6
sys/include/net/sock/udp.h
View File

@ -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`.

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

@ -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,

24
sys/net/gnrc/network_layer/ipv6/nib/_nib-internal.h
View File

@ -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.
*