From 26fd846da1d3b25703990ea9fc744d4f645d1dd1 Mon Sep 17 00:00:00 2001 From: Sven Anderson Date: Sat, 2 Oct 2021 00:35:37 +0900 Subject: [PATCH] docs: update comments of preview and deprecated APIs Signed-off-by: Sven Anderson --- rbd/admin/imagespec.go | 14 ++++++++------ rbd/admin/task.go | 36 ++++++++++++++++++------------------ rbd/mirror.go | 4 +++- rbd/rbd.go | 6 ++---- rbd/snapshot.go | 7 ++++--- rgw/admin/caps.go | 6 ++++-- 6 files changed, 39 insertions(+), 34 deletions(-) diff --git a/rbd/admin/imagespec.go b/rbd/admin/imagespec.go index c95d99b..f632541 100644 --- a/rbd/admin/imagespec.go +++ b/rbd/admin/imagespec.go @@ -9,18 +9,19 @@ import ( // ImageSpec values are used to identify an RBD image wherever Ceph APIs // require an image_spec/image_id_spec using image name/id and optional // pool and namespace. -// PREVIEW +// PREVIEW type ImageSpec struct { spec string } // NewImageSpec is used to construct an ImageSpec given an image name/id // and optional namespace and pool names. +// PREVIEW +// // NewImageSpec constructs an ImageSpec to identify an RBD image and thus // requires image name/id, whereas NewLevelSpec constructs LevelSpec to // identify entire pool, pool namespace or single RBD image, all of which // requires pool name. -// PREVIEW func NewImageSpec(pool, namespace, image string) ImageSpec { var s string if pool != "" && namespace != "" { @@ -34,10 +35,11 @@ func NewImageSpec(pool, namespace, image string) ImageSpec { } // NewRawImageSpec returns a ImageSpec directly based on the spec string -// argument without constructing it from component values. This should only be -// used if NewImageSpec can not create the imagespec value you want to pass to -// ceph. -// PREVIEW +// argument without constructing it from component values. +// PREVIEW +// +// This should only be used if NewImageSpec can not create the imagespec value +// you want to pass to ceph. func NewRawImageSpec(spec string) ImageSpec { return ImageSpec{spec} } diff --git a/rbd/admin/task.go b/rbd/admin/task.go index 428b428..99ca0e5 100644 --- a/rbd/admin/task.go +++ b/rbd/admin/task.go @@ -7,22 +7,20 @@ import ( "github.com/ceph/go-ceph/internal/commands" ) -// TaskAdmin encapsulates management functions for -// ceph rbd task operations. -// PREVIEW +// TaskAdmin encapsulates management functions for ceph rbd task operations. +// PREVIEW type TaskAdmin struct { conn ccom.MgrCommander } -// Task returns a TaskAdmin type for -// managing ceph rbd task operations. -// PREVIEW +// Task returns a TaskAdmin type for managing ceph rbd task operations. +// PREVIEW func (ra *RBDAdmin) Task() *TaskAdmin { return &TaskAdmin{conn: ra.conn} } // TaskRefs contains the action name and information about the image. -// PREVIEW +// PREVIEW type TaskRefs struct { Action string `json:"action"` PoolName string `json:"pool_name"` @@ -32,7 +30,7 @@ type TaskRefs struct { } // TaskResponse contains the information about the task added on an image. -// PREVIEW +// PREVIEW type TaskResponse struct { Sequence int `json:"sequence"` ID string `json:"id"` @@ -57,11 +55,12 @@ func parseTaskResponseList(res commands.Response) ([]TaskResponse, error) { return taskResponseList, err } -// AddFlatten adds a background task to flatten a cloned image based on the supplied image spec. +// AddFlatten adds a background task to flatten a cloned image based on the +// supplied image spec. +// PREVIEW // // Similar To: // rbd task add flatten -// PREVIEW func (ta *TaskAdmin) AddFlatten(img ImageSpec) (TaskResponse, error) { m := map[string]string{ "prefix": "rbd task add flatten", @@ -71,11 +70,12 @@ func (ta *TaskAdmin) AddFlatten(img ImageSpec) (TaskResponse, error) { return parseTaskResponse(commands.MarshalMgrCommand(ta.conn, m)) } -// AddRemove adds a background task to remove an image based on the supplied image spec. +// AddRemove adds a background task to remove an image based on the supplied +// image spec. +// PREVIEW // // Similar To: // rbd task add remove -// PREVIEW func (ta *TaskAdmin) AddRemove(img ImageSpec) (TaskResponse, error) { m := map[string]string{ "prefix": "rbd task add remove", @@ -85,12 +85,12 @@ func (ta *TaskAdmin) AddRemove(img ImageSpec) (TaskResponse, error) { return parseTaskResponse(commands.MarshalMgrCommand(ta.conn, m)) } -// AddTrashRemove adds a background task to remove an image from the trash based on the -// supplied image id spec. +// AddTrashRemove adds a background task to remove an image from the trash based +// on the supplied image id spec. +// PREVIEW // // Similar To: // rbd task add trash remove -// PREVIEW func (ta *TaskAdmin) AddTrashRemove(img ImageSpec) (TaskResponse, error) { m := map[string]string{ "prefix": "rbd task add trash remove", @@ -101,10 +101,10 @@ func (ta *TaskAdmin) AddTrashRemove(img ImageSpec) (TaskResponse, error) { } // List pending or running asynchronous tasks. +// PREVIEW // // Similar To: // rbd task list -// PREVIEW func (ta *TaskAdmin) List() ([]TaskResponse, error) { m := map[string]string{ "prefix": "rbd task list", @@ -114,10 +114,10 @@ func (ta *TaskAdmin) List() ([]TaskResponse, error) { } // GetTaskByID returns pending or running asynchronous task using id. +// PREVIEW // // Similar To: // rbd task list -// PREVIEW func (ta *TaskAdmin) GetTaskByID(taskID string) (TaskResponse, error) { m := map[string]string{ "prefix": "rbd task list", @@ -128,10 +128,10 @@ func (ta *TaskAdmin) GetTaskByID(taskID string) (TaskResponse, error) { } // Cancel a pending or running asynchronous task. +// PREVIEW // // Similar To: // rbd task cancel -// PREVIEW func (ta *TaskAdmin) Cancel(taskID string) (TaskResponse, error) { m := map[string]string{ "prefix": "rbd task cancel", diff --git a/rbd/mirror.go b/rbd/mirror.go index 9592e68..b45a09a 100644 --- a/rbd/mirror.go +++ b/rbd/mirror.go @@ -746,7 +746,9 @@ func (iter *MirrorImageGlobalStatusIter) Next() (*GlobalMirrorImageIDAndStatus, } // Close terminates iteration regardless if iteration was completed and -// frees any associated resources. (DEPRECATED) +// frees any associated resources. +// +// Deprecated: not required func (*MirrorImageGlobalStatusIter) Close() error { return nil } diff --git a/rbd/rbd.go b/rbd/rbd.go index 56ff3fc..7d5b1ce 100644 --- a/rbd/rbd.go +++ b/rbd/rbd.go @@ -327,11 +327,9 @@ func (image *Image) Rename(destname string) error { return err } -// Open the rbd image (DEPRECATED). +// Open the rbd image. // -// Deprecated: The Open function was provided in earlier versions of the API -// and now exists to support older code. The use of OpenImage and -// OpenImageReadOnly is preferred. +// Deprecated: use OpenImage and OpenImageReadOnly instead func (image *Image) Open(args ...interface{}) error { if err := image.validate(imageNeedsIOContext | imageNeedsName); err != nil { return err diff --git a/rbd/snapshot.go b/rbd/snapshot.go index 3166ca9..5085982 100644 --- a/rbd/snapshot.go +++ b/rbd/snapshot.go @@ -147,9 +147,10 @@ func (snapshot *Snapshot) IsProtected() (bool, error) { return cIsProtected != 0, nil } -// Set updates the rbd image (not the Snapshot) such that the snapshot -// is the source of readable data (DEPRECATED). -// Refer the SetSnapshot method of the Image type instead. +// Set updates the rbd image (not the Snapshot) such that the snapshot is the +// source of readable data. +// +// Deprecated: use the SetSnapshot method of the Image type instead // // Implements: // int rbd_snap_set(rbd_image_t image, const char *snapname); diff --git a/rgw/admin/caps.go b/rgw/admin/caps.go index fcc9389..a2ce69a 100644 --- a/rgw/admin/caps.go +++ b/rgw/admin/caps.go @@ -10,8 +10,9 @@ import ( ) // AddUserCap adds the capabilities for a user. +// PREVIEW +// // On Success, it returns the updated list of UserCaps for the user. -// PREVIEW func (api *API) AddUserCap(ctx context.Context, uid, userCap string) ([]UserCapSpec, error) { if uid == "" { return nil, errMissingUserID @@ -36,8 +37,9 @@ func (api *API) AddUserCap(ctx context.Context, uid, userCap string) ([]UserCapS } // RemoveUserCap removes the capabilities from a user. +// PREVIEW +// // On Success, it returns the updated list of UserCaps for the user. -// PREVIEW func (api *API) RemoveUserCap(ctx context.Context, uid, userCap string) ([]UserCapSpec, error) { if uid == "" { return nil, errMissingUserID