From 6d2b85ed063aed723267ba1cd621743bd45bd004 Mon Sep 17 00:00:00 2001 From: iphydf Date: Fri, 30 Sep 2016 14:52:10 +0100 Subject: Minor documentation fixes. - Fixed incorrect parameter names (documented name didn't match code name). - Removed `@return` from functions that return `void`. - Make sure every parameter is documented. This required moving the planes and strides documentation to the function docs. --- other/apidsl/tox.in.h | 50 ++++++++++++++++++++++++------------------------- other/apidsl/toxav.in.h | 29 ++++++++++++++-------------- 2 files changed, 39 insertions(+), 40 deletions(-) (limited to 'other/apidsl') diff --git a/other/apidsl/tox.in.h b/other/apidsl/tox.in.h index 91cd0eb8..3cad8f4b 100644 --- a/other/apidsl/tox.in.h +++ b/other/apidsl/tox.in.h @@ -683,8 +683,8 @@ uint8_t[size] savedata { /** * Store all information associated with the tox instance to a byte array. * - * @param data A memory region large enough to store the tox instance data. - * Call $size to find the number of bytes required. If this parameter + * @param savedata A memory region large enough to store the tox instance + * data. Call $size to find the number of bytes required. If this parameter * is NULL, this function has no effect. */ get(); @@ -965,8 +965,8 @@ inline namespace self { * Call $size to find out how much memory to allocate for * the result. * - * @param status A valid memory location large enough to hold the status message. - * If this parameter is NULL, the function has no effect. + * @param status_message A valid memory location large enough to hold the + * status message. If this parameter is NULL, the function has no effect. */ get(); } @@ -976,7 +976,7 @@ inline namespace self { /** * Set the client's user status. * - * @param user_status One of the user statuses listed in the enumeration above. + * @param status One of the user statuses listed in the enumeration above. */ set(); @@ -1151,8 +1151,8 @@ inline namespace self { * * Call $size to determine the number of elements to allocate. * - * @param list A memory region with enough space to hold the friend list. If - * this parameter is NULL, this function has no effect. + * @param friend_list A memory region with enough space to hold the friend + * list. If this parameter is NULL, this function has no effect. */ get(); } @@ -1532,9 +1532,9 @@ namespace friend { * @param message The message they sent along with the request. * @param length The size of the message byte array. */ - typedef void(const uint8_t[PUBLIC_KEY_SIZE] public_key - //, uint32_t time_delta - , const uint8_t[length <= MAX_MESSAGE_LENGTH] message); + typedef void(const uint8_t[PUBLIC_KEY_SIZE] public_key, + // uint32_t time_delta, + const uint8_t[length <= MAX_MESSAGE_LENGTH] message); } @@ -1550,9 +1550,9 @@ namespace friend { * * @see ${event request} for more information on time_delta. */ - typedef void(uint32_t friend_number - //, uint32_t time_delta - , MESSAGE_TYPE type, + typedef void(uint32_t friend_number, + // uint32_t time_delta, + MESSAGE_TYPE type, const uint8_t[length <= MAX_MESSAGE_LENGTH] message); } @@ -1752,18 +1752,18 @@ namespace file { NOT_FOUND, } - /** - * Copy the file id associated to the file transfer to a byte array. - * - * @param friend_number The friend number of the friend the file is being - * transferred to or received from. - * @param file_number The friend-specific identifier for the file transfer. - * @param file_id A memory region of at least $FILE_ID_LENGTH bytes. If - * this parameter is NULL, this function has no effect. - * - * @return true on success. - */ uint8_t[FILE_ID_LENGTH] file_id { + /** + * Copy the file id associated to the file transfer to a byte array. + * + * @param friend_number The friend number of the friend the file is being + * transferred to or received from. + * @param file_number The friend-specific identifier for the file transfer. + * @param file_id A memory region of at least $FILE_ID_LENGTH bytes. If + * this parameter is NULL, this function has no effect. + * + * @return true on success. + */ get(uint32_t friend_number, uint32_t file_number) with error for get; } @@ -2371,8 +2371,6 @@ namespace conference { /** * Copy a list of valid conference IDs into the array chatlist. Determine how much space * to allocate for the array with the `$size` function. - * - * @return The number of elements copied to the array, or 0 if chatlist is set to NULL. */ get(); } diff --git a/other/apidsl/toxav.in.h b/other/apidsl/toxav.in.h index 07808eec..6e3e9c17 100644 --- a/other/apidsl/toxav.in.h +++ b/other/apidsl/toxav.in.h @@ -557,23 +557,24 @@ namespace video { /** * The function type for the ${event receive_frame} callback. * + * The size of plane data is derived from width and height as documented + * below. + * + * Strides represent padding for each plane that may or may not be present. + * You must handle strides in your image processing code. Strides are + * negative if the image is bottom-up hence why you MUST abs() it when + * calculating plane buffer size. + * * @param friend_number The friend number of the friend who sent a video frame. * @param width Width of the frame in pixels. * @param height Height of the frame in pixels. - * @param y - * @param u - * @param v Plane data. - * The size of plane data is derived from width and height where - * Y = MAX(width, abs(ystride)) * height, - * U = MAX(width/2, abs(ustride)) * (height/2) and - * V = MAX(width/2, abs(vstride)) * (height/2). - * @param ystride - * @param ustride - * @param vstride Strides data. Strides represent padding for each plane - * that may or may not be present. You must handle strides in - * your image processing code. Strides are negative if the - * image is bottom-up hence why you MUST abs() it when - * calculating plane buffer size. + * @param y Luminosity plane. Size = MAX(width, abs(ystride)) * height. + * @param u U chroma plane. Size = MAX(width/2, abs(ustride)) * (height/2). + * @param v V chroma plane. Size = MAX(width/2, abs(vstride)) * (height/2). + * + * @param ystride Luminosity plane stride. + * @param ustride U chroma plane stride. + * @param vstride V chroma plane stride. */ typedef void(uint32_t friend_number, uint16_t width, uint16_t height, const uint8_t *y, const uint8_t *u, const uint8_t *v, -- cgit v1.2.3