docs: update comments of preview and deprecated APIs

Signed-off-by: Sven Anderson <sven@redhat.com>

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
+// argument without constructing it from component values.
-// used if NewImageSpec can not create the imagespec value you want to pass to
+//  PREVIEW
-// ceph.
+//
-// 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}
 }

rbd/admin/task.go

@@ -7,22 +7,20 @@ import (
 	"github.com/ceph/go-ceph/internal/commands"
 )
 
-// TaskAdmin encapsulates management functions for
+// TaskAdmin encapsulates management functions for ceph rbd task operations.
-// ceph rbd task operations.
+//  PREVIEW
-// PREVIEW
 type TaskAdmin struct {
 	conn ccom.MgrCommander
 }
 
-// Task returns a TaskAdmin type for
+// Task returns a TaskAdmin type for managing ceph rbd task operations.
-// managing ceph rbd task operations.
+//  PREVIEW
-// 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 <image_spec>
-// 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 <image_spec>
-// 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
+// AddTrashRemove adds a background task to remove an image from the trash based
-// supplied image id spec.
+// on the supplied image id spec.
+//  PREVIEW
 //
 // Similar To:
 //  rbd task add trash remove <image_id_spec>
-// 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 <task_id>
-// 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 <task_id>
-// PREVIEW
 func (ta *TaskAdmin) Cancel(taskID string) (TaskResponse, error) {
 	m := map[string]string{
 		"prefix":  "rbd task cancel",

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
 }

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
+// Deprecated: use OpenImage and OpenImageReadOnly instead
-// and now exists to support older code. The use of OpenImage and
-// OpenImageReadOnly is preferred.
 func (image *Image) Open(args ...interface{}) error {
 	if err := image.validate(imageNeedsIOContext | imageNeedsName); err != nil {
 		return err

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
+// Set updates the rbd image (not the Snapshot) such that the snapshot is the
-// is the source of readable data (DEPRECATED).
+// source of readable data.
-// Refer the SetSnapshot method of the Image type instead.
+//
+// Deprecated: use the SetSnapshot method of the Image type instead
 //
 // Implements:
 //  int rbd_snap_set(rbd_image_t image, const char *snapname);

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