From: Jos Collin Date: Wed, 24 Oct 2018 07:37:41 +0000 (+0530) Subject: rados: fix admin/build-doc warnings X-Git-Tag: 3.2-0~106^2 X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=a2a7f417b843632b021b1f64b78a807309ed24a5;p=ceph-ci.git rados: fix admin/build-doc warnings Fixed admin/build-doc warnings in librados.h and rados_types.h Signed-off-by: Jos Collin --- diff --git a/src/include/rados/librados.h b/src/include/rados/librados.h index 80064b23b05..86334802615 100644 --- a/src/include/rados/librados.h +++ b/src/include/rados/librados.h @@ -236,14 +236,25 @@ typedef void *rados_list_ctx_t; */ typedef void * rados_object_list_cursor; +/** + * @struct rados_object_list_item + * + * The item populated by rados_object_list in + * the results array. + */ typedef struct rados_object_list_item { + + /// oid length size_t oid_length; + /// name of the object char *oid; - + /// namespace length size_t nspace_length; + /// the object namespace char *nspace; - + /// locator length size_t locator_length; + /// object locator char *locator; } rados_object_list_item; @@ -285,15 +296,20 @@ struct rados_pool_stat_t { uint64_t num_object_clones; /// num_objects * num_replicas uint64_t num_object_copies; + /// number of objects missing on primary uint64_t num_objects_missing_on_primary; /// number of objects found on no OSDs uint64_t num_objects_unfound; /// number of objects replicated fewer times than they should be /// (but found on at least one OSD) uint64_t num_objects_degraded; + /// number of objects read uint64_t num_rd; + /// objects read in KB uint64_t num_rd_kb; + /// number of objects written uint64_t num_wr; + /// objects written in KB uint64_t num_wr_kb; }; @@ -302,7 +318,13 @@ struct rados_pool_stat_t { * Cluster-wide usage information */ struct rados_cluster_stat_t { - uint64_t kb, kb_used, kb_avail; + /// total device size + uint64_t kb; + /// total used + uint64_t kb_used; + /// total available/free + uint64_t kb_avail; + /// number of objects uint64_t num_objects; }; @@ -1177,7 +1199,7 @@ CEPH_RADOS_API int rados_object_list_cursor_cmp(rados_ioctx_t io, rados_object_list_cursor lhs, rados_object_list_cursor rhs); /** - * @return the number of items set in the result array + * @return the number of items set in the results array */ CEPH_RADOS_API int rados_object_list(rados_ioctx_t io, const rados_object_list_cursor start, @@ -1198,10 +1220,11 @@ CEPH_RADOS_API void rados_object_list_free( * global namespace. Expected use case is when you are iterating * in parallel, with `m` workers, and each worker taking an id `n`. * + * @param io ioctx * @param start start of the range to be sliced up (inclusive) * @param finish end of the range to be sliced up (exclusive) - * @param m how many chunks to divide start-finish into * @param n which of the m chunks you would like to get cursors for + * @param m how many chunks to divide start-finish into * @param split_start cursor populated with start of the subrange (inclusive) * @param split_finish cursor populated with end of the subrange (exclusive) */ @@ -1589,7 +1612,7 @@ CEPH_RADOS_API int rados_trunc(rados_ioctx_t io, const char *oid, * @param io the context in which to perform the comparison * @param o name of the object * @param cmp_buf buffer containing bytes to be compared with object contents - * @param cmp_len length to compare and size of @cmp_buf in bytes + * @param cmp_len length to compare and size of @c cmp_buf in bytes * @param off object byte offset at which to start the comparison * @returns 0 on success, negative error code on failure, * (-MAX_ERRNO - mismatch_off) on mismatch @@ -2215,6 +2238,7 @@ CEPH_RADOS_API int rados_aio_flush_async(rados_ioctx_t io, * * @param io ioctx * @param o object name + * @param completion what to do when the stat is complete * @param psize where to store object size * @param pmtime where to store modification time * @returns 0 on success, negative error code on failure @@ -2230,7 +2254,7 @@ CEPH_RADOS_API int rados_aio_stat(rados_ioctx_t io, const char *o, * @param o the name of the object to compare with * @param completion what to do when the comparison is complete * @param cmp_buf buffer containing bytes to be compared with object contents - * @param cmp_len length to compare and size of @cmp_buf in bytes + * @param cmp_len length to compare and size of @c cmp_buf in bytes * @param off object byte offset at which to start the comparison * @returns 0 on success, negative error code on failure, * (-MAX_ERRNO - mismatch_off) on mismatch @@ -2261,7 +2285,8 @@ CEPH_RADOS_API int rados_aio_cancel(rados_ioctx_t io, * Classes in ceph.git can be found in src/cls subdirectories * * @param io the context in which to call the method - * @param oid the object to call the method on + * @param o name of the object + * @param completion what to do when the exec completes * @param cls the name of the class * @param method the name of the method * @param in_buf where to find input @@ -2339,6 +2364,7 @@ CEPH_RADOS_API int rados_aio_rmxattr(rados_ioctx_t io, const char *o, * * @param io the context in which to list xattrs * @param oid name of the object + * @param completion what to do when the getxattrs completes * @param iter where to store the iterator * @returns 0 on success, negative error code on failure */ @@ -2671,15 +2697,15 @@ CEPH_RADOS_API int rados_notify(rados_ioctx_t io, const char *o, uint64_t ver, * @param reply_buffer_len pointer to size of reply buffer * @returns 0 on success, negative error code on failure */ +CEPH_RADOS_API int rados_aio_notify(rados_ioctx_t io, const char *o, + rados_completion_t completion, + const char *buf, int buf_len, + uint64_t timeout_ms, char **reply_buffer, + size_t *reply_buffer_len); CEPH_RADOS_API int rados_notify2(rados_ioctx_t io, const char *o, const char *buf, int buf_len, uint64_t timeout_ms, char **reply_buffer, size_t *reply_buffer_len); -CEPH_RADOS_API int rados_aio_notify(rados_ioctx_t io, const char *o, - rados_completion_t completion, - const char *buf, int buf_len, - uint64_t timeout_ms, char **reply_buffer, - size_t *reply_buffer_len); /** * Acknolwedge receipt of a notify @@ -2827,6 +2853,7 @@ CEPH_RADOS_API void rados_release_write_op(rados_write_op_t write_op); /** * Set flags for the last operation added to this write_op. * At least one op must have been added to the write_op. + * @param write_op operation to add this action to * @param flags see librados.h constants beginning with LIBRADOS_OP_FLAG */ CEPH_RADOS_API void rados_write_op_set_flags(rados_write_op_t write_op, @@ -2858,7 +2885,7 @@ CEPH_RADOS_API void rados_write_op_assert_version(rados_write_op_t write_op, uin * * @param write_op operation to add this action to * @param cmp_buf buffer containing bytes to be compared with object contents - * @param cmp_len length to compare and size of @cmp_buf in bytes + * @param cmp_len length to compare and size of @c cmp_buf in bytes * @param off object byte offset at which to start the comparison * @param prval returned result of comparison, 0 on success, negative error code * on failure, (-MAX_ERRNO - mismatch_off) on mismatch @@ -2987,7 +3014,7 @@ CEPH_RADOS_API void rados_write_op_write_full(rados_write_op_t write_op, * @param write_op operation to add this action to * @param buffer bytes to write * @param data_len length of buffer - * @param write_len total number of bytes to write, as a multiple of @data_len + * @param write_len total number of bytes to write, as a multiple of @c data_len * @param offset offset to write to */ CEPH_RADOS_API void rados_write_op_writesame(rados_write_op_t write_op, @@ -3197,6 +3224,7 @@ CEPH_RADOS_API void rados_release_read_op(rados_read_op_t read_op); /** * Set flags for the last operation added to this read_op. * At least one op must have been added to the read_op. + * @param read_op operation to add this action to * @param flags see librados.h constants beginning with LIBRADOS_OP_FLAG */ CEPH_RADOS_API void rados_read_op_set_flags(rados_read_op_t read_op, int flags); @@ -3227,7 +3255,7 @@ CEPH_RADOS_API void rados_read_op_assert_version(rados_read_op_t read_op, uint64 * * @param read_op operation to add this action to * @param cmp_buf buffer containing bytes to be compared with object contents - * @param cmp_len length to compare and size of @cmp_buf in bytes + * @param cmp_len length to compare and size of @c cmp_buf in bytes * @param off object byte offset at which to start the comparison * @param prval returned result of comparison, 0 on success, negative error code * on failure, (-MAX_ERRNO - mismatch_off) on mismatch @@ -3345,12 +3373,11 @@ CEPH_RADOS_API void rados_read_op_read(rados_read_op_t read_op, * Compute checksum from object data * * @param read_op operation to add this action to - * @param oid the name of the object to checksum * @param type the checksum algorithm to utilize * @param init_value the init value for the algorithm * @param init_value_len the length of the init value + * @param offset the offset to start checksumming in the object * @param len the number of bytes to checksum - * @param off the offset to start checksumming in the object * @param chunk_size optional length-aligned chunk size for checksums * @param pchecksum where to store the checksum result for this action * @param checksum_len the number of bytes available for the result @@ -3523,7 +3550,7 @@ CEPH_RADOS_API void rados_read_op_omap_get_vals_by_keys(rados_read_op_t read_op, * @param read_op operation to add this action to * @param keys array of pointers to keys to get * @param num_keys the number of strings in keys - * @param keys_len array of size_t's describing each key len (in bytes) + * @param key_lens array of size_t's describing each key len (in bytes) * @param iter where to store the iterator * @param prval where to store the return value from this action */ @@ -3695,7 +3722,7 @@ CEPH_RADOS_API void rados_unset_osdmap_full_try(rados_ioctx_t io); /** * Enable an application on a pool * - * @param ioctx pool ioctx + * @param io pool ioctx * @param app_name application name * @param force 0 if only single application per pool * @returns 0 on success, negative error code on failure @@ -3710,10 +3737,9 @@ CEPH_RADOS_API int rados_application_enable(rados_ioctx_t io, * -ERANGE is returned. Otherwise, the buffers are filled with the application * names, with a '\0' after each. * - * @param ioctx pool ioctx - * @param app_name application name + * @param io pool ioctx * @param values buffer in which to store application names - * @param vals_len number of bytes in values buffer + * @param values_len number of bytes in values buffer * @returns 0 on success, negative error code on failure * @returns -ERANGE if either buffer is too short */ @@ -3723,7 +3749,7 @@ CEPH_RADOS_API int rados_application_list(rados_ioctx_t io, char *values, /** * Get application metadata value from pool * - * @param ioctx pool ioctx + * @param io pool ioctx * @param app_name application name * @param key metadata key * @param value result buffer @@ -3738,7 +3764,7 @@ CEPH_RADOS_API int rados_application_metadata_get(rados_ioctx_t io, /** * Set application metadata on a pool * - * @param ioctx pool ioctx + * @param io pool ioctx * @param app_name application name * @param key metadata key * @param value metadata key @@ -3752,7 +3778,7 @@ CEPH_RADOS_API int rados_application_metadata_set(rados_ioctx_t io, /** * Remove application metadata from a pool * - * @param ioctx pool ioctx + * @param io pool ioctx * @param app_name application name * @param key metadata key * @returns 0 on success, negative error code on failure @@ -3771,10 +3797,10 @@ CEPH_RADOS_API int rados_application_metadata_remove(rados_ioctx_t io, * in and -ERANGE is returned. Otherwise, the buffers are filled with * the keys and values of the metadata, with a '\0' after each. * - * @param ioctx pool ioctx + * @param io pool ioctx * @param app_name application name * @param keys buffer in which to store key names - * @param keys_len number of bytes in keys buffer + * @param key_len number of bytes in keys buffer * @param values buffer in which to store values * @param vals_len number of bytes in values buffer * @returns 0 on success, negative error code on failure @@ -3809,6 +3835,7 @@ CEPH_RADOS_API int rados_application_metadata_list(rados_ioctx_t io, * @param cmd an array of char *'s representing the command * @param cmdlen count of valid entries in cmd * @param inbuf any bulk input data (crush map, etc.) + * @param inbuflen input buffer length * @param outbuf double pointer to output buffer * @param outbuflen pointer to output buffer length * @param outs double pointer to status string @@ -3836,6 +3863,7 @@ CEPH_RADOS_API int rados_mon_command(rados_t cluster, const char **cmd, * @param cmd an array of char *'s representing the command * @param cmdlen count of valid entries in cmd * @param inbuf any bulk input data (crush map, etc.) + * @param inbuflen input buffer length * @param outbuf double pointer to output buffer * @param outbuflen pointer to output buffer length * @param outs double pointer to status string @@ -3864,6 +3892,7 @@ CEPH_RADOS_API int rados_mgr_command(rados_t cluster, const char **cmd, * @param cmd an array of char *'s representing the command * @param cmdlen count of valid entries in cmd * @param inbuf any bulk input data (crush map, etc.) + * @param inbuflen input buffer length * @param outbuf double pointer to output buffer * @param outbuflen pointer to output buffer length * @param outs double pointer to status string diff --git a/src/include/rados/rados_types.h b/src/include/rados/rados_types.h index 5156b7562fa..0712f489148 100644 --- a/src/include/rados/rados_types.h +++ b/src/include/rados/rados_types.h @@ -8,14 +8,17 @@ * One item from list_watchers */ struct obj_watch_t { + /// Address of the Watcher char addr[256]; + /// Watcher ID int64_t watcher_id; + /// Cookie uint64_t cookie; + /// Timeout in Seconds uint32_t timeout_seconds; }; /** - * @defines * * Pass as nspace argument to rados_ioctx_set_namespace() * before calling rados_nobjects_list_open() to return