From: Josh Durgin Date: Thu, 29 Dec 2011 00:00:25 +0000 (-0800) Subject: doc: clarify librados return codes X-Git-Tag: v0.40~29 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=0e19062c8297fab2d79852dc8a62935ae9d6bb3c;p=ceph.git doc: clarify librados return codes Adding a second @returns for specific error codes makes the sphinx output more readable. Signed-off-by: Josh Durgin --- diff --git a/src/include/rados/librados.h b/src/include/rados/librados.h index f256d720952c..0a1980f196b8 100644 --- a/src/include/rados/librados.h +++ b/src/include/rados/librados.h @@ -299,8 +299,8 @@ int rados_conf_parse_env(rados_t cluster, const char *var); * @param cluster cluster handle to configure * @param option option to set * @param value value of the option - * @returns 0 on success, negative error code on failure. -ENOENT is - * returned when the option is not a Ceph configuration option. + * @returns 0 on success, negative error code on failure + * @returns -ENOENT when the option is not a Ceph configuration option */ int rados_conf_set(rados_t cluster, const char *option, const char *value); @@ -311,9 +311,9 @@ int rados_conf_set(rados_t cluster, const char *option, const char *value); * @param option which option to read * @param buf where to write the configuration value * @param len the size of buf in bytes - * @returns 0 on success, negative error code on failure. - * -ENAMETOOLONG is returned if the buffer is too short to contain the - * requested value. + * @returns 0 on success, negative error code on failure + * @returns -ENAMETOOLONG if the buffer is too short to contain the + * requested value */ int rados_conf_get(rados_t cluster, const char *option, char *buf, size_t len); @@ -683,8 +683,8 @@ int rados_ioctx_selfmanaged_snap_rollback(rados_ioctx_t io, const char *oid, rad * @param seq the newest snapshot sequence number for the pool * @param snaps array of snapshots in sorted by descending id * @param num_snaps how many snaphosts are in the snaps array - * @returns 0 on success, negative error code on failure. - * -EINVAL is returned if snaps are not in descending order. + * @returns 0 on success, negative error code on failure + * @returns -EINVAL if snaps are not in descending order */ int rados_ioctx_selfmanaged_snap_set_write_ctx(rados_ioctx_t io, rados_snap_t seq, rados_snap_t *snaps, int num_snaps); @@ -698,8 +698,8 @@ int rados_ioctx_selfmanaged_snap_set_write_ctx(rados_ioctx_t io, rados_snap_t se * @param io the pool to read from * @param snaps where to store the results * @param maxlen the number of rados_snap_t that fit in the snaps array - * @returns number of snapshots on success, negative error code on failure. - * -ERANGE is returned if the snaps array is too short. + * @returns number of snapshots on success, negative error code on failure + * @returns -ERANGE is returned if the snaps array is too short */ int rados_ioctx_snap_list(rados_ioctx_t io, rados_snap_t *snaps, int maxlen); @@ -1041,8 +1041,8 @@ int rados_tmap_put(rados_ioctx_t io, const char *o, const char *buf, size_t bufl * @param o object name * @param buf buffer * @param buflen buffer length in bytes - * @returns 0 on success, negative error code on failure. - * -ERANGE is returned if buf isn't big enough + * @returns 0 on success, negative error code on failure + * @returns -ERANGE if buf isn't big enough */ int rados_tmap_get(rados_ioctx_t io, const char *o, char *buf, size_t buflen); @@ -1063,8 +1063,8 @@ int rados_tmap_get(rados_ioctx_t io, const char *o, char *buf, size_t buflen); * @param in_len length of in_buf in bytes * @param buf where to store output * @param out_len length of buf in bytes - * @returns For methods that return data, the length of the output, or - * -ERANGE if out_buf does not have enough space to store it. For + * @returns the length of the output, or + * -ERANGE if out_buf does not have enough space to store it (For methods that return data). For * methods that don't return data, the return value is * method-specific. */ @@ -1180,8 +1180,7 @@ int rados_aio_is_safe(rados_completion_t c); * message is received before the complete message * * @param c async operation to inspect - * @returns return value of the operation (see sychronous version of - * operation for expected values) + * @returns return value of the operation */ int rados_aio_get_return_value(rados_completion_t c); @@ -1198,7 +1197,8 @@ void rados_aio_release(rados_completion_t c); /** * Write data to an object asynchronously * - * Queues the write and returns. + * Queues the write and returns. The return value of the completion + * will be 0 on success, negative error code on failure. * * @param io the context in which the write will occur * @param oid name of the object @@ -1218,6 +1218,9 @@ int rados_aio_write(rados_ioctx_t io, const char *oid, * * Queues the append and returns. * + * The return value of the completion will be 0 on success, negative + * error code on failure. + * * @param io the context to operate in * @param oid the name of the object * @param completion what to do when the append is safe and complete @@ -1237,6 +1240,9 @@ int rados_aio_append(rados_ioctx_t io, const char *oid, * it is atomically truncated and then written. * Queues the write_full and returns. * + * The return value of the completion will be 0 on success, negative + * error code on failure. + * * @param io the io context in which the write will occur * @param oid name of the object * @param completion what to do when the write_full is safe and complete @@ -1255,6 +1261,9 @@ int rados_aio_write_full(rados_ioctx_t io, const char *oid, * The io context determines the snapshot to read from, if any was set * by rados_ioctx_snap_set_read(). * + * The return value of the completion will be number of bytes read on + * success, negative error code on failure. + * * @note only the 'complete' callback of the completion will be called. * * @param io the context in which to perform the read @@ -1336,9 +1345,8 @@ typedef void (*rados_watchcb_t)(uint8_t opcode, uint64_t ver, void *arg); * @param handle where to store the internal id assigned to this watch * @param watchcb what to do when a notify is received on this object * @param arg application defined data to pass when watchcb is called - * @returns 0 on success, negative error code on failure. -ERANGE is - * returned, and the watch is not registered, if the version of the - * object is greater than ver. + * @returns 0 on success, negative error code on failure + * @returns -ERANGE if the version of the object is greater than ver */ int rados_watch(rados_ioctx_t io, const char *o, uint64_t ver, uint64_t *handle, rados_watchcb_t watchcb, void *arg);