kaspar/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2025-12-15 17:43:51 +01:00
Code Releases Activity

tree-wide: mixed back of documentation fixes

Browse Source 
This fixes a number of documentation issues that LLVM/clang would flag
with `-Wdocumentation`.
This commit is contained in:
Marian Buschsieweke 2025-04-07 13:58:47 +02:00
parent 3b6d95fa66
commit db0be36345
No known key found for this signature in database
GPG Key ID: 758BD52517F79C41
13 changed files with 71 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
drivers/include/periph/adc.h
View File

@ -142,8 +142,6 @@ void adc_continuous_begin(adc_res_t res);
*
* @note requires the `periph_adc_continuous` feature
*
* @brief Sample a value from the given ADC line
*
* @return the sampled value on success
*/
int32_t adc_continuous_sample(adc_t line);

4
drivers/sdmmc/sdmmc.c
View File

@ -1134,7 +1134,7 @@ static int _assert_card(sdmmc_dev_t *dev)
* are deselected by this and go into the state `stby`.
*
* @param[in] dev SDIO/SD/MMC device to be used
* @param[in] card Card or embedded device to be selected or deselected
* @param[in] select If `true`, card will be selected, otherwise deselected
*
* @return 0 on success or negative error code on error
*/
@ -1287,7 +1287,6 @@ out:
* the `stby` state (deselected) when CMD10 is used to read the CID.
*
* @param[in] dev SD/MMC device to be used
* @param[in] card Card or embedded device
* @param[in] cmd Command to be used
* (CMD2 in state `ready` or CMD10 in state `stdby')
*
@ -1348,7 +1347,6 @@ static int _read_cid(sdmmc_dev_t *dev, uint8_t cmd)
* state to read the CSD (deselected).
*
* @param[in] dev SD/MMC device to be used
* @param[in] card Card or embedded device
*
* @return 0 on success or negative error code on error
*/

2
drivers/sdmmc/sdmmc_sdhc.c
View File

@ -718,7 +718,7 @@ static int _wait_sdhc_busy(sdhc_t *sdhc)
/**
* @brief Wait for a given event while checking for errors
*
* @param state SDHC device context
* @param sdhc_dev SDHC device generating the event
* @param event Event to wait for [SDHC_NISTR_*]
* @param error_mask Mask of errors to be checked [SDHC_EISTR_*]
* @param reset Reset type in case of errors

4
pkg/fatfs/fatfs_diskio/mtd/mtd_diskio.c
View File

@ -147,8 +147,8 @@ DRESULT disk_write(BYTE pdrv, const BYTE *buff, DWORD sector, UINT count)
* @brief perform miscellaneous low-level control functions
*
* @param[in] pdrv Physical drive nmuber (0..FF_VOLUMES-1)
* @param[in out] cmd Control code
* @param[in] sector Buffer to send/receive control data
* @param[in,out] cmd Control code
* @param[in] buff Buffer to send/receive control data
*
* @return RES_OK if no error occurred
* @return RES_PARERR if cmd is unknown or

16
sys/ecc/hamming256.c
View File

@ -197,15 +197,17 @@ static void compute256(const uint8_t *data, uint8_t *code, uint8_t padding)
}
/**
* @brief Verifies and corrects a 256-bytes block of data using the given 22-bits
* hamming code.
* @brief Verifies and corrects a 256-bytes block of data using the given
* 22-bits hamming code.
*
* @param data Data buffer to check.
* @param originalCode Hamming code to use for verifying the data.
* @param padding Amount of zeroes to be appended to the data such that it sizes
* equals 256 bytes
* @param pucData Data buffer to check.
* @param pucOriginalCode Hamming code to use for verifying the data.
* @param padding Amount of zeroes to be appended to the data such
* that it sizes equals 256 bytes
*
* @return 0 if there is no error, otherwise returns a HAMMING_ERROR code.
* @retval 0 Success
* @retval !=0 Failure (return value is a HAMMING_ERROR code
* indicating the cause)
*/
uint8_t verify256( uint8_t *pucData, const uint8_t *pucOriginalCode, uint8_t padding )
{

2
sys/hashes/md5.c
View File

@ -132,7 +132,7 @@ static const uint32_t T[4][16] = {
* Oh... and the algorithm requires that there be at least one padding byte. The
* first padding byte has a value of 0x80, and any others are 0x00.
*
* @param[in|out] abcd Pointer to an array of four unsigned longwords
* @param[in,out] abcd Pointer to an array of four unsigned longwords
* @param[in] block Array of bytes, must be 64 bytes in size
*/
static void permute(uint32_t abcd[4], const uint8_t block[64] )

4
sys/include/bloom.h
View File

@ -169,8 +169,6 @@ void bloom_init(bloom_t *bloom, size_t size, uint8_t *bitfield, hashfp_t *hashes
* @brief Delete a Bloom filter.
*
* @param bloom The condemned
* @return nothing
*
*/
void bloom_del(bloom_t *bloom);
@ -183,8 +181,6 @@ void bloom_del(bloom_t *bloom);
* @param bloom Bloom filter
* @param buf string to add
* @param len the length of the string @p buf
* @return nothing
*
*/
void bloom_add(bloom_t *bloom, const uint8_t *buf, size_t len);

77
sys/include/net/nanocoap_sock.h
View File

@ -610,8 +610,11 @@ ssize_t nanocoap_sock_unobserve_url(const char *url, coap_observe_client_t *ctx)
* @param[out] response buffer to write response to
* @param[in] len_max length of @p buffer
*
* @returns length of response payload on success
* @returns @see nanocoap_sock_request_cb on error
* @return length of response payload or error code
* @retval >=0 Success, return value is the length of the response payload
* @retval <0 Failure, return value is the error code. See
@ref nanocoap_sock_request_cb on error for the list of
error codes
*/
ssize_t nanocoap_sock_get(nanocoap_sock_t *sock, const char *path,
void *response, size_t len_max);
@ -624,8 +627,11 @@ ssize_t nanocoap_sock_get(nanocoap_sock_t *sock, const char *path,
* @param[out] response buffer for the response, may be NULL
* @param[in] len_max length of @p response
*
* @returns length of response payload on success
* @returns @see nanocoap_sock_request_cb on error
* @return length of response payload or error code
* @retval >=0 Success, return value is the length of the response payload
* @retval <0 Failure, return value is the error code. See
@ref nanocoap_sock_request_cb on error for the list of
error codes
*/
ssize_t nanocoap_sock_get_non(nanocoap_sock_t *sock, const char *path,
void *response, size_t len_max);
@ -640,8 +646,11 @@ ssize_t nanocoap_sock_get_non(nanocoap_sock_t *sock, const char *path,
* @param[out] response buffer for the response, may be NULL
* @param[in] len_max length of @p response
*
* @returns length of response payload on success
* @returns @see nanocoap_sock_request_cb on error
* @return length of response payload or error code
* @retval >=0 Success, return value is the length of the response payload
* @retval <0 Failure, return value is the error code. See
@ref nanocoap_sock_request_cb on error for the list of
error codes
*/
ssize_t nanocoap_sock_put(nanocoap_sock_t *sock, const char *path,
const void *request, size_t len,
@ -657,10 +666,11 @@ ssize_t nanocoap_sock_put(nanocoap_sock_t *sock, const char *path,
* @param[out] response buffer for the response, may be NULL
* @param[in] len_max length of @p response
*
* @returns length of response payload on success
* @returns 0 if the request was sent and no response buffer was provided,
* independently of success (because no response is requested in that case)
* @returns @see nanocoap_sock_request_cb on error
* @return length of response payload or error code
* @retval >=0 Success, return value is the length of the response payload
* @retval <0 Failure, return value is the error code. See
@ref nanocoap_sock_request_cb on error for the list of
error codes
*/
ssize_t nanocoap_sock_put_non(nanocoap_sock_t *sock, const char *path,
const void *request, size_t len,
@ -692,8 +702,12 @@ ssize_t nanocoap_sock_put_url(const char *url,
* @param[out] response buffer for the response, may be NULL
* @param[in] len_max length of @p response
*
* @returns length of response payload on success
* @returns @see nanocoap_sock_request_cb on error
* @return length of response payload or error code
* @retval >0 Success, return value is the length of the response payload
* @retval 0 Success, response contained no payload
* @retval <0 Failure, return value is the error code. See
@ref nanocoap_sock_request_cb on error for the list of
error codes
*/
ssize_t nanocoap_sock_post(nanocoap_sock_t *sock, const char *path,
const void *request, size_t len,
@ -709,10 +723,12 @@ ssize_t nanocoap_sock_post(nanocoap_sock_t *sock, const char *path,
* @param[out] response buffer for the response, may be NULL
* @param[in] len_max length of @p response
*
* @returns length of response payload on success
* @returns 0 if the request was sent and no response buffer was provided,
* independently of success (because no response is requested in that case)
* @returns @see nanocoap_sock_request_cb on error
* @return length of response payload or error code
* @retval >0 Success, return value is the length of the response payload
* @retval 0 Success, response contained no payload
* @retval <0 Failure, return value is the error code. See
@ref nanocoap_sock_request_cb on error for the list of
error codes
*/
ssize_t nanocoap_sock_post_non(nanocoap_sock_t *sock, const char *path,
const void *request, size_t len,
@ -745,8 +761,11 @@ ssize_t nanocoap_sock_post_url(const char *url,
* @param[out] response buffer for the response, may be NULL
* @param[in] len_max length of @p response
*
* @returns length of response payload on success
* @returns @see nanocoap_sock_request_cb on error
* @return length of response payload or error code
* @retval >=0 Success, return value is the length of the response payload
* @retval <0 Failure, return value is the error code. See
@ref nanocoap_sock_request_cb on error for the list of
error codes
*/
ssize_t nanocoap_sock_fetch(nanocoap_sock_t *sock, const char *path,
const void *request, size_t len,
@ -763,10 +782,11 @@ ssize_t nanocoap_sock_fetch(nanocoap_sock_t *sock, const char *path,
* @param[out] response buffer for the response, may be NULL
* @param[in] len_max length of @p response
*
* @returns length of response payload on success
* @returns 0 if the request was sent and no response buffer was provided,
* independently of success (because no response is requested in that case)
* @returns @see nanocoap_sock_request_cb on error
* @return length of response payload or error code
* @retval >=0 Success, return value is the length of the response payload
* @retval <0 Failure, return value is the error code. See
@ref nanocoap_sock_request_cb on error for the list of
error codes
*/
ssize_t nanocoap_sock_fetch_non(nanocoap_sock_t *sock, const char *path,
const void *request, size_t len,
@ -795,8 +815,10 @@ ssize_t nanocoap_sock_fetch_url(const char *url,
* @param[in] sock socket to use for the request
* @param[in] path remote path (with query) to delete
*
* @returns 0 on success
* @returns @see nanocoap_sock_request_cb on error
* @retval 0 Success, return value is the length of the response payload
* @retval <0 Failure, return value is the error code. See
@ref nanocoap_sock_request_cb on error for the list of
error codes
*/
ssize_t nanocoap_sock_delete(nanocoap_sock_t *sock, const char *path);
@ -966,8 +988,11 @@ ssize_t nanocoap_sock_request_cb(nanocoap_sock_t *sock, coap_pkt_t *pkt,
* @param[in] len Total length of the buffer associated with the
* request
*
* @returns length of response on success
* @returns @see nanocoap_sock_request_cb on error
* @return length of response payload or error code
* @retval >=0 Success, return value is the length of the response payload
* @retval <0 Failure, return value is the error code. See
@ref nanocoap_sock_request_cb on error for the list of
error codes
*/
ssize_t nanocoap_request(coap_pkt_t *pkt, const sock_udp_ep_t *local,
const sock_udp_ep_t *remote, size_t len);

2
sys/include/senml.h
View File

@ -453,7 +453,6 @@ static inline senml_numeric_t senml_duration_ms(int32_t ms)
*
* @param n Numeric value to set.
* @param ms Duration in milliseconds.
* @return Numeric representation of the duration.
*/
static inline void senml_set_duration_ms(senml_numeric_t *n, int32_t ms)
{
@ -476,7 +475,6 @@ static inline senml_numeric_t senml_duration_us(int32_t us)
*
* @param n Numeric value to set.
* @param us Duration in microseconds.
* @return Numeric representation of the duration.
*/
static inline void senml_set_duration_us(senml_numeric_t *n, int32_t us)
{

2
sys/net/gnrc/netif/gnrc_netif.c
View File

@ -1735,8 +1735,6 @@ static event_t *_gnrc_netif_fetch_event(gnrc_netif_t *netif)
*
* @param[in] netif gnrc_netif instance to operate on
* @param[out] msg pointer to message buffer to write the first received message
*
* @return >0 if msg contains a new message
*/
static void _process_events_await_msg(gnrc_netif_t *netif, msg_t *msg)
{

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

@ -683,7 +683,7 @@ static inline _nib_offl_entry_t *_nib_dc_add(const ipv6_addr_t *next_hop,
/**
* @brief Removes a destination cache entry
*
* @param[in,out] nib_dr An entry.
* @param[in,out] nib_offl Destination entry to remove.
*
* Corresponding on-link entry is removed, too.
*
@ -735,7 +735,7 @@ void _nib_pl_remove(_nib_offl_entry_t *nib_offl);
* @brief Removes a prefix from the prefix list as well as the addresses
* associated with the prefix.
*
* @param[in,out] nib_offl An entry.
* @param[in,out] pfx The prefix to remove.
*
* Corresponding on-link entry is removed, too.
*/
@ -872,8 +872,8 @@ void _nib_ft_get(const _nib_offl_entry_t *dst, gnrc_ipv6_nib_ft_t *fte);
* @return 0, on success.
* @return -ENETUNREACH, when no route was found.
*/
int _nib_get_route(const ipv6_addr_t *dst, gnrc_pktsnip_t *ctx,
gnrc_ipv6_nib_ft_t *entry);
int _nib_get_route(const ipv6_addr_t *dst, gnrc_pktsnip_t *pkt,
gnrc_ipv6_nib_ft_t *fte);
#if IS_ACTIVE(CONFIG_GNRC_IPV6_NIB_QUEUE_PKT) || DOXYGEN
/**

2
sys/newlib_syscalls_default/syscalls.c
View File

@ -464,7 +464,7 @@ int _fstat_r(struct _reent *r, int fd, struct stat *buf)
*
* @param[in] r pointer to reent structure
* @param[in] name path to file
* @param[out] buf pointer to stat struct to fill
* @param[out] st pointer to stat struct to fill
*
* @return 0 on success
* @return -1 on error, @c r->_errno set to a constant from errno.h to indicate the error

2
tests/unittests/tests-ztimer64/tests-ztimer64-core.c
View File

@ -50,7 +50,7 @@ static void setup(void)
}
/**
* @brief
* @brief Test ztimer64_now()
*/
static void test_ztimer64_now(void)
{