From 5ffc595d0d58b85f92eef3e68db79affee752401 Mon Sep 17 00:00:00 2001 From: Enji Cooper Date: Mon, 29 Apr 2019 09:59:53 +0200 Subject: [PATCH] Document more @return values with doxygen for APIs Summary: * Note that SSH_ERROR can be returned on error in `ssh_channel_get_exit_status` and `ssh_channel_get_session`. * Note the return codes for `channel_open` and `grow_window`; although these are internal APIs, it's best to document their behavior. * Replace `@returns` use with `@return`. While Doxygen supports the former as a synonym for `@return`, it isn't documented in the manual (and might not be supported by other downstream documentation tools). Signed-off-by: Enji Cooper Reviewed-by: Andreas Schneider Reviewed-by: Jakub Jelen Test Plan: n/a Reviewers: #libssh, asn Differential Revision: https://bugs.libssh.org/D15 --- src/channels.c | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/src/channels.c b/src/channels.c index dd25151a..4fbcec1d 100644 --- a/src/channels.c +++ b/src/channels.c @@ -269,6 +269,8 @@ static int ssh_channel_open_termination(void *c){ * @param[in] maxpacket The maximum packet size allowed (like MTU). * * @param[in] payload The buffer containing additional payload for the query. + * + * @return SSH_OK if successful; SSH_ERROR otherwise. */ static int channel_open(ssh_channel channel, const char *type, int window, int maxpacket, ssh_buffer payload) { @@ -364,6 +366,7 @@ ssh_channel ssh_channel_from_local(ssh_session session, uint32_t id) { * @param session SSH session * @param channel SSH channel * @param minimumsize The minimum acceptable size for the new window. + * @return SSH_OK if successful; SSH_ERROR otherwise. */ static int grow_window(ssh_session session, ssh_channel channel, int minimumsize) { uint32_t new_window = minimumsize > WINDOWBASE ? minimumsize : WINDOWBASE; @@ -419,7 +422,7 @@ error: * @param[in] packet The buffer to parse packet from. The read pointer will * be moved after the call. * - * @returns The related ssh_channel, or NULL if the channel is + * @return The related ssh_channel, or NULL if the channel is * unknown or the packet is invalid. */ static ssh_channel channel_from_msg(ssh_session session, ssh_buffer packet) { @@ -1329,9 +1332,9 @@ static int ssh_waitsession_unblocked(void *s){ * @brief Flushes a channel (and its session) until the output buffer * is empty, or timeout elapsed. * @param channel SSH channel - * @returns SSH_OK On success, - * SSH_ERROR on error - * SSH_AGAIN Timeout elapsed (or in nonblocking mode) + * @return SSH_OK On success, + * SSH_ERROR On error. + * SSH_AGAIN Timeout elapsed (or in nonblocking mode). */ int ssh_channel_flush(ssh_channel channel){ return ssh_blocking_flush(channel->session, SSH_TIMEOUT_DEFAULT); @@ -3103,8 +3106,8 @@ static int ssh_channel_exit_status_termination(void *c){ * * @param[in] channel The channel to get the status from. * - * @returns The exit status, -1 if no exit status has been returned - * (yet). + * @return The exit status, -1 if no exit status has been returned + * (yet), or SSH_ERROR on error. * @warning This function may block until a timeout (or never) * if the other side is not willing to close the channel. * @@ -3214,7 +3217,7 @@ static int count_ptrs(ssh_channel *ptrs) { * * @return SSH_OK on a successful operation, SSH_EINTR if the * select(2) syscall was interrupted, then relaunch the - * function. + * function, or SSH_ERROR on error. */ int ssh_channel_select(ssh_channel *readchans, ssh_channel *writechans, ssh_channel *exceptchans, struct timeval * timeout) {