Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 1 commit into from
Jan 10, 2018
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions core/include/lifo.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand All @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion sys/include/net/gnrc/ipv6/nib/nc.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion sys/include/net/gnrc/ipv6/nib/pl.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
28 changes: 14 additions & 14 deletions sys/include/net/gnrc/ndp.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand All @@ -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,
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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);
Expand All @@ -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).
Expand Down
6 changes: 3 additions & 3 deletions sys/include/net/gnrc/netif/internal.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions sys/include/net/gnrc/pktqueue.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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.
Expand All @@ -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
*/
Expand Down
14 changes: 7 additions & 7 deletions sys/include/net/gnrc/priority_pktqueue.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)
{
Expand All @@ -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
*/
Expand All @@ -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
*/
Expand All @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion sys/include/net/ndp.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The reference doesn't name any max value, where does 7 come from - or did I miss that?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we focus on the topic of this PR? This is about replacing "may not" with "must not"! In the meantime I will research why that is.

Copy link
Member Author

@miri64 miri64 Jan 10, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is in fact GNRC-specific (so a follow-up should add something like […] with @ref net_gnrc).

*/
#define NDP_DAD_TRANSMIT_NUMOF (1U)
#define NDP_MAX_ANYCAST_MS_DELAY (1000U) /**< MAX_ANYCAST_DELAY_TIME (in ms) */
Expand Down
2 changes: 1 addition & 1 deletion sys/include/net/sixlowpan.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion sys/include/net/sixlowpan/nd.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

dito here, I haven't found any reference on a maximum RFC 6775, 3.3:

The response to an address registration might not be immediate, since
in route-over configurations the 6LR might perform Duplicate Address
Detection against the 6LBR. A host retransmits the Address
Registration Option until it is acknowledged by the receipt of an
Address Registration Option.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(The same answer as for #8277 (comment) applies here)

*/
#define SIXLOWPAN_ND_REG_TRANSMIT_NUMOF (3U)
/**
Expand Down
6 changes: 3 additions & 3 deletions sys/include/net/sock/udp.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down
6 changes: 3 additions & 3 deletions sys/net/gnrc/network_layer/ipv6/nib/_nib-arsm.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
Loading