* Fix all the typo found by kwrite tool. * Rephrase the description of lsm_connect C struct as Tony suggested. * Renamed 'Exception' to 'Error' in C API document as C does not have exception.
Signed-off-by: Gris Ge <[email protected]> --- doc/c_api_user_guide.md | 62 ++++++++++++++++++++++++------------------------ doc/py_api_user_guide.md | 45 ++++++++++++++++------------------- 2 files changed, 52 insertions(+), 55 deletions(-) diff --git a/doc/c_api_user_guide.md b/doc/c_api_user_guide.md index f9ede07..f92e74c 100644 --- a/doc/c_api_user_guide.md +++ b/doc/c_api_user_guide.md @@ -15,15 +15,15 @@ title: C API User Guide * [Appendix.A. Asynchronous Job Control][aa] * [Appendix.B. Bit Map][ab] * [Appendix.C. Misc Functions and Structures][ac] -* [Appendix.D. Exceptions -- `lsm_error`][ad] +* [Appendix.D. Errors -- `lsm_error`][ad] This document provides detail information about how to use -LibStorageMgmt C API for storage system management and assuming you have +LibStorageMgmt C API for storage system management and assumes you have read the [LibStorageMgmt User Guide][1]. -The sample C code could be found at git repo [client_example.c][2]. +The sample C code can be found at git repository [client_example.c][2]. -To libstoragemgmt in your project: +To use LibStorageMgmt in your project: * Install `libstoragemgmt-devel` package. @@ -58,7 +58,7 @@ To libstoragemgmt in your project: LSM_CLIENT_FLAG_RSVD); ``` -* Invoke libstoragemgmt methods: +* Invoke LibStorageMgmt methods: ```c /** Use lsm_pool_list as example */ @@ -84,11 +84,11 @@ To libstoragemgmt in your project: } ``` -* Handle exceptions: +* Handle errors: - Please refer to [Appendix.D. Exceptions][ad] for detail. + Please refer to [Appendix.D. Errors][ad] for detail. - These common exceptions might be raised by every methods: + These common errors might be returned by every methods: * `LSM_ERR_LIB_BUG` @@ -106,7 +106,7 @@ To libstoragemgmt in your project: * `LSM_ERR_NO_MEMORY` - Sample code to handle exceptions: + Sample code to handle errors: ```c lsm_error *lsm_err = lsm_error_last_get(lsm_conn); @@ -125,8 +125,8 @@ To libstoragemgmt in your project: * [1.1. Make Connection -- `lsm_connect_password`][0101] * [1.2. Close Connection -- `lsm_connect_close`][0102] -The `lsm_connect` struct is opaque holding internal data, there is -no public member in it. +The `lsm_connect` struct is an opaque data structure which holds +internal data, there is no public member in it. ### 1.1. Make Connection -- `lsm_connect_password` @@ -148,22 +148,22 @@ Parameters: conn (output, lsm_connect **) Output pointer of lsm_connect type. timeout (input, uint32_t) - Maximum milliseconds of runtime for each method before raising + Maximum milliseconds of runtime for each method before returning error with LSM_ERR_TIMEOUT. If set to 0, it means no timeout. e (output, lsm_error_ptr *) Output pointer of lsm_error_ptr type. - Please refer to section [Appendix.D. Exceptions] for detail. + Please refer to section [Appendix.D. Errors] for detail. flags (input, lsm_flag) Reserved for future use. Should be set as LSM_CLIENT_FLAG_RSVD. Returns: rc (int) LSM_ERR_OK if connection was created without any error. - When error found, please retrive error information from output + When error found, please retrieve error information from output pointer argument 'e'. - Please refer to section [Appendix.D. Exceptions] for detail. + Please refer to section [Appendix.D. Errors] for detail. Capability: No capability needed for this method. -SpecialExceptions: +SpecialErrors: LSM_ERR_PLUGIN_AUTH_FAILED LSM_ERR_PLUGIN_IPC_FAIL LSM_ERR_PLUGIN_SOCKET_PERMISSION @@ -199,11 +199,11 @@ Parameters: Returns: rc (int) LSM_ERR_OK if connection was created without any error. - Please refer to section [Appendix.D. Exceptions] for error + Please refer to section [Appendix.D. Errors] for error number. Capability: No capability needed for this method. -SpecialExceptions: +SpecialErrors: N/A Sample: int rc = lsm_connect_close(lsm_conn, LSM_CLIENT_FLAG_RSVD); @@ -312,16 +312,16 @@ Parameters: as NULL. Please refer to [Appendix.C.1 String Array] section for 'lsm_string_list' structure members. - This memory requires manuall free via lsm_string_list_free(). + This memory requires manually free via lsm_string_list_free(). flags (input, lsm_flag) Reserved for future use. Should be set as LSM_CLIENT_FLAG_RSVD. Returns: rc (int) LSM_ERR_OK if connection was created without any error. - Please refer to section [Appendix.D. Exceptions] for detail. + Please refer to section [Appendix.D. Errors] for detail. Capability: LSM_CAP_POOL_MEMBER_INFO -SpecialExceptions: +SpecialErrors: LSM_ERR_NO_SUPPORT LSM_ERR_NOT_FOUND_POOL Sample: @@ -454,10 +454,10 @@ Parameters: Returns: rc (int) LSM_ERR_OK if connection was created without any error. - Please refer to section [Appendix.D. Exceptions] for detail. + Please refer to section [Appendix.D. Errors] for detail. Capability: LSM_CAP_VOLUME_RAID_INFO -SpecialExceptions: +SpecialErrors: LSM_ERR_NO_SUPPORT LSM_ERR_NOT_FOUND_VOLUME Sample: @@ -536,10 +536,10 @@ Parameters: Returns: rc (int) LSM_ERR_OK if connection was created without any error. - Please refer to section [Appendix.D. Exceptions] for detail. + Please refer to section [Appendix.D. Errors] for detail. Capability: LSM_CAP_VOLUME_RAID_CREATE -SpecialExceptions: +SpecialErrors: LSM_ERR_NO_SUPPORT LSM_ERR_NOT_FOUND_SYSTEM Sample: @@ -594,7 +594,7 @@ Usage: The new volume and new pool will created within the same system of provided disks. This method does not allow duplicate call, if duplicate call - was isssue, LSM_ERR_DISK_NOT_FREE will be returned. + was issue, LSM_ERR_DISK_NOT_FREE will be returned. User should check lsm_disk_status_get() for LSM_DISK_STATUS_FREE before invoking this method. Parameters: @@ -605,7 +605,7 @@ Parameters: The name for new volume. The requested volume name might be ignored due to restriction of hardware RAID vendors. - The pool name will be automatically choosed by plugin. + The pool name will be automatically chose by plugin. raid_type (input, lsm_volume_raid_type *) The pointer to lsm_volume_raid_type. The possible values are: @@ -639,10 +639,10 @@ Parameters: Returns: rc (int) LSM_ERR_OK if connection was created without any error. - Please refer to section [Appendix.D. Exceptions] for detail. + Please refer to section [Appendix.D. Errors] for detail. Capability: LSM_CAP_VOLUME_RAID_CREATE -SpecialExceptions: +SpecialErrors: LSM_ERR_NO_SUPPORT LSM_ERR_NOT_FOUND_DISK LSM_ERR_DISK_NOT_FREE @@ -733,7 +733,7 @@ Sample: #### Appendix.C.1.7 `lsm_string_list_append()` #### Appendix.C.1.8 `lsm_string_list_delete()` -## Appendix.D. Exceptions -- `lsm_error` +## Appendix.D. Errors -- `lsm_error` [01]: #1.-connection----lsm_connect [0101]: #1.1.-make-connection----lsm_connect_password @@ -763,4 +763,4 @@ Sample: [01]: #appendix.c.1.6-lsm_string_list_size() [01]: #appendix.c.1.7-lsm_string_list_append() [01]: #appendix.c.1.8-lsm_string_list_delete() -[ad]: #appendix.d.-exceptions----lsm_error +[ad]: #appendix.d.-errors----lsm_error diff --git a/doc/py_api_user_guide.md b/doc/py_api_user_guide.md index ff597ab..b36bbea 100644 --- a/doc/py_api_user_guide.md +++ b/doc/py_api_user_guide.md @@ -557,7 +557,7 @@ Pool is the only place a volume or a file system could created from. * `lsm.Pool.ELEMENT_TYPE_DELTA` - The pool which is holding the dalta of snapshot or replication. + The pool which is holding the delta of snapshot or replication. * `lsm.Pool.ELEMENT_TYPE_SYS_RESERVED` @@ -601,13 +601,13 @@ Pool is the only place a volume or a file system could created from. * `lsm.Pool.TOTAL_SPACE_NOT_FOUND` - Integer: -1. Indicate plugin failed to retrived total space of the + Integer: -1. Indicate plugin failed to retrieved total space of the pool. * `lsm.Pool.FREE_SPACE_NOT_FOUND` - Integer: -1. Indicate plugin failed to retrived free space of the + Integer: -1. Indicate plugin failed to retrieved free space of the pool. ### 4.3. Query Pools -- `lsm.Client.pools()` @@ -855,7 +855,7 @@ Disk is used to assemble storage pool or as a spare disk. * `lsm.Disk.STATUS_INITIALIZING` - Disk is not functional and is initialiaing. + Disk is not functional and is initializing. It could be: * Initialiaing new disk. @@ -974,8 +974,9 @@ block device(s). * `vpd83` - String. Fromat: '[0-9a-f]{32}', SCSI VPD0x83 as identifier of - volume. Also knowned as 'wwid' in device-mapper-multipath. + String. Format: '6[0-9a-f]{31}' or '[235][0-9a-f]{15}', SCSI VPD0x83 type 3 + NAA identifier of volume. Also known as 'wwid' in device-mapper-multipath + and 'ID_WWN' of udev. * `block_size` @@ -1040,7 +1041,7 @@ block device(s). * `lsm.Volume.PROVISION_UNKNOWN` Used by lsm.Client.volume_create() in 'provisioning' parameter. - Indicating leting plugin or storage to decide on creating a thin or + Indicating plugin or storage will decide on creating a thin or full volume. * `lsm.Volume.SUPPORTED_SEARCH_KEYS` @@ -1156,7 +1157,7 @@ Sample: (job_id, new_lsm_vol) = lsm_client.volume_create( lsm_pool, "test_volue", size_bytes) if job_id: - # we get async job, wait untile finished + # we get asynchronous job, wait until finished # Check Appendix.A print "New volume created:%s(%s)" % (new_lsm_vol.name, new_lsm_vol.id) @@ -1211,7 +1212,7 @@ Sample: to_delete_vol = lsm_client.volumes()[0] job_id = lsm_client.volume_delete(to_delete_vol) if job_id: - # we get async job, wait untile finished + # we get asynchronous job, wait until finished # Check Appendix.A print "Volume %s(%s) deleted" % ( to_delete_vol.name, to_delete_vol.id) @@ -1234,7 +1235,7 @@ Version: Usage: Resize (grow or shrink) a volume. Please be warned when shrinking the size of volume, there might be a data corruption or data lose. - It's stongly suggested to perform a data backup before shrinking any + It's strongly suggested to perform a data backup before shrinking any volume. Size grow is mandatory if lsm.Capabilities.VOLUME_RESIZE is supported. The resized volume will hold larger size than requested due to @@ -1264,7 +1265,7 @@ Sample: (job_id, new_lsm_vol) = lsm_client.volume_resize( to_resize_vol, new_size_bytes) if job_id: - # we get async job, wait untile finished + # we get asynchronous job, wait until finished # Check Appendix.A print "Volume %s resized to %d(%s)" % ( new_lsm_vol.name, new_lsm_vol.size_bytes, @@ -1305,13 +1306,13 @@ lsm_client = lsm.Client('sim://') lsm_vol = lsm_client.volumes()[0] job_id = lsm_client.volume_disable(lsm_vol) if job_id: - # we get async job, wait untile finished + # we get asynchronous job, wait until finished # Check Appendix.A print "Volume %s is offline" % lsm_vol.name job_id = lsm_client.volume_enable(lsm_vol) if job_id: - # we get async job, wait untile finished + # we get asynchronous job, wait until finished # Check Appendix.A print "Volume %s is enabled" % lsm_vol.name Capability: @@ -1347,13 +1348,13 @@ Sample: lsm_vol = lsm_client.volumes()[0] job_id = lsm_client.volume_disable(lsm_vol) if job_id: - # we get async job, wait untile finished + # we get asynchronous job, wait until finished # Check Appendix.A print "Volume %s is disabled" % lsm_vol.name job_id = lsm_client.volume_enable(lsm_vol) if job_id: - # we get async job, wait untile finished + # we get asynchronous job, wait until finished # Check Appendix.A print "Volume %s is enabled" % lsm_vol.name Capability: @@ -1536,7 +1537,7 @@ Parameters: The name for new volume. The requested volume name might be ignored due to restriction of hardware RAID vendors. - The pool name will be automatically choosed by plugin. + The pool name will be automatically chose by plugin. raid_type (int) The RAID type for the RAID group, possible values are: Volume.RAID_TYPE_RAID0 @@ -1678,8 +1679,6 @@ will be treated as a access group. ### 7.3. Query Access Group -- `lsm.Client.access_groups()` - -```rst ```rst lsm.Client.access_groups( self, search_key=None, search_value=None, flags=lsm.Client.FLAG_RSVD) @@ -1801,8 +1800,6 @@ Capability: # Support creating iSCSI IQN access group. ``` - - ### 7.5. Delete Access Group -- `lsm.Client.access_group_delete()` @@ -1931,7 +1928,7 @@ SpecialExceptions: # group. lsm.ErrorNumber.LAST_INIT_IN_ACCESS_GROUP # Defined access group is masked to volumes and - # we are removeing its last initiator. This is not + # we are removing its last initiator. This is not # allowed in LSM. Try to unmask volumes first. Sample: lsm_client = lsm.Client('sim://') @@ -2034,7 +2031,7 @@ Sample: new_vol = lsm_client.volume_create( lsm_pool, "test_volue", size_bytes) if job_id: - # we get async job, wait untile finished + # we get asynchronous job, wait until finished # Check Appendix.A print "New volume created:%s(%s)" % (new_lsm_vol.name, new_lsm_vol.id) @@ -2300,7 +2297,7 @@ Sample: * `lsm.ErrorNumber.JOB_STARTED` - This is only used in C API to indicate a ASYNC job was created. + This is only used in C API to indicate a asynchronous job was created. * `lsm.ErrorNumber.TIMEOUT` @@ -2331,7 +2328,7 @@ Sample: * `lsm.ErrorNumber.NO_STATE_CHANGE` - Indicate requested no state change for requested action. It offten + Indicate requested no state change for requested action. It often caused by repeated call. * `lsm.ErrorNumber.NETWORK_CONNREFUSED` -- 2.1.4 _______________________________________________ libstoragemgmt-devel mailing list [email protected] https://lists.fedorahosted.org/mailman/listinfo/libstoragemgmt-devel
