[nspcc-dev#1247] *: Clarify docs about returned errors from `apistatu…

…s` package

`apistatus` package provides types which implement build-in `error`
interface. Add `error of type` pattern when documenting these errors in
order to clarify how these errors should be handled (e.g. `errors.Is` is
not good).

Signed-off-by: Leonard Lyubich <leonard@nspcc.ru>

pkg/core/container/storage.go

@@ -15,7 +15,7 @@ type Source interface {
 	// It returns the pointer to requested container and any error encountered.
 	//
 	// Get must return exactly one non-nil value.
-	// Get must return apistatus.ContainerNotFound if the container is not in storage.
+	// Get must return an error of type apistatus.ContainerNotFound if the container is not in storage.
 	//
 	// Implementations must not retain the container pointer and modify
 	// the container through it.

pkg/innerring/rpc.go

@@ -61,7 +61,7 @@ func (c *ClientCache) Get(info clientcore.NodeInfo) (clientcore.Client, error) {
 // GetSG polls the container from audit task to get the object by id.
 // Returns storage groups structure from received object.
 //
-// Returns apistatus.ObjectNotFound if storage group is missing.
+// Returns an error of type apistatus.ObjectNotFound if storage group is missing.
 func (c *ClientCache) GetSG(task *audit.Task, id *oidSDK.ID) (*storagegroup.StorageGroup, error) {
 	sgAddress := new(addressSDK.Address)
 	sgAddress.SetContainerID(task.ContainerID())

pkg/innerring/settlement.go

@@ -169,7 +169,7 @@ func (s settlementDeps) ContainerNodes(e uint64, cid *cid.ID) ([]common.NodeInfo
 
 // SGInfo returns audit.SGInfo by object address.
 //
-// Returns apistatus.ObjectNotFound if storage group is missing.
+// Returns an error of type apistatus.ObjectNotFound if storage group is missing.
 func (s settlementDeps) SGInfo(addr *addressSDK.Address) (audit.SGInfo, error) {
 	cn, nm, err := s.buildContainer(0, addr.ContainerID())
 	if err != nil {

pkg/local_object_storage/blobovnicza/delete.go

@@ -26,7 +26,7 @@ func (p *DeletePrm) SetAddress(addr *addressSDK.Address) {
 // Returns any error encountered that
 // did not allow to completely delete the object.
 //
-// Returns apistatus.ObjectNotFound if the object to be deleted is not in blobovnicza.
+// Returns an error of type apistatus.ObjectNotFound if the object to be deleted is not in blobovnicza.
 //
 // Should not be called in read-only configuration.
 func (b *Blobovnicza) Delete(prm *DeletePrm) (*DeleteRes, error) {

pkg/local_object_storage/blobovnicza/get.go

@@ -32,7 +32,7 @@ func (p *GetRes) Object() []byte {
 // Returns any error encountered that
 // did not allow to completely read the object.
 //
-// Returns apistatus.ObjectNotFound if requested object is not
+// Returns an error of type apistatus.ObjectNotFound if requested object is not
 // presented in Blobovnicza.
 func (b *Blobovnicza) Get(prm *GetPrm) (*GetRes, error) {
 	var (

pkg/local_object_storage/blobstor/delete_big.go

@@ -21,7 +21,7 @@ type DeleteBigRes struct{}
 // Returns any error encountered that did not allow
 // to completely remove the object.
 //
-// Returns apistatus.ObjectNotFound if there is no object to delete.
+// Returns an error of type apistatus.ObjectNotFound if there is no object to delete.
 func (b *BlobStor) DeleteBig(prm *DeleteBigPrm) (*DeleteBigRes, error) {
 	err := b.fsTree.Delete(prm.addr)
 	if errors.Is(err, fstree.ErrFileNotFound) {

pkg/local_object_storage/blobstor/delete_small.go

@@ -17,7 +17,7 @@ type DeleteSmallRes struct{}
 // Returns any error encountered that did not allow
 // to completely remove the object.
 //
-// Returns apistatus.ObjectNotFound if there is no object to delete.
+// Returns an error of type apistatus.ObjectNotFound if there is no object to delete.
 func (b *BlobStor) DeleteSmall(prm *DeleteSmallPrm) (*DeleteSmallRes, error) {
 	return b.blobovniczas.delete(prm)
 }

pkg/local_object_storage/blobstor/get_big.go

@@ -24,7 +24,7 @@ type GetBigRes struct {
 // Returns any error encountered that
 // did not allow to completely read the object.
 //
-// Returns apistatus.ObjectNotFound if requested object is not
+// Returns an error of type apistatus.ObjectNotFound if requested object is not
 // presented in shallow dir.
 func (b *BlobStor) GetBig(prm *GetBigPrm) (*GetBigRes, error) {
 	// get compressed object data

pkg/local_object_storage/blobstor/get_range_big.go

@@ -27,7 +27,7 @@ type GetRangeBigRes struct {
 // did not allow to completely read the object payload range.
 //
 // Returns ErrRangeOutOfBounds if requested object range is out of bounds.
-// Returns apistatus.ObjectNotFound if object is missing.
+// Returns an error of type apistatus.ObjectNotFound if object is missing.
 func (b *BlobStor) GetRangeBig(prm *GetRangeBigPrm) (*GetRangeBigRes, error) {
 	// get compressed object data
 	data, err := b.fsTree.Get(prm.addr)

pkg/local_object_storage/blobstor/get_range_small.go

@@ -21,7 +21,7 @@ type GetRangeSmallRes struct {
 // did not allow to completely read the object payload range.
 //
 // Returns ErrRangeOutOfBounds if requested object range is out of bounds.
-// Returns apistatus.ObjectNotFound if requested object is missing in blobovnicza(s).
+// Returns an error of type apistatus.ObjectNotFound if requested object is missing in blobovnicza(s).
 func (b *BlobStor) GetRangeSmall(prm *GetRangeSmallPrm) (*GetRangeSmallRes, error) {
 	return b.blobovniczas.getRange(prm)
 }

pkg/local_object_storage/blobstor/get_small.go

@@ -19,7 +19,7 @@ type GetSmallRes struct {
 // Returns any error encountered that
 // did not allow to completely read the object.
 //
-// Returns apistatus.ObjectNotFound if requested object is missing in blobovnicza(s).
+// Returns an error of type apistatus.ObjectNotFound if requested object is missing in blobovnicza(s).
 func (b *BlobStor) GetSmall(prm *GetSmallPrm) (*GetSmallRes, error) {
 	return b.blobovniczas.get(prm)
 }

pkg/local_object_storage/engine/get.go

@@ -42,8 +42,8 @@ func (r *GetRes) Object() *objectSDK.Object {
 // Returns any error encountered that
 // did not allow to completely read the object part.
 //
-// Returns apistatus.ObjectNotFound if requested object is missing in local storage.
-// Returns apistatus.ObjectAlreadyRemoved if object has been marked as removed.
+// Returns an error of type apistatus.ObjectNotFound if requested object is missing in local storage.
+// Returns an error of type apistatus.ObjectAlreadyRemoved if object has been marked as removed.
 //
 // Returns an error if executions are blocked (see BlockExecution).
 func (e *StorageEngine) Get(prm *GetPrm) (res *GetRes, err error) {

pkg/local_object_storage/engine/head.go

@@ -55,8 +55,8 @@ func (r *HeadRes) Header() *objectSDK.Object {
 // Returns any error encountered that
 // did not allow to completely read the object header.
 //
-// Returns apistatus.ObjectNotFound if requested object is missing in local storage.
-// Returns apistatus.ObjectAlreadyRemoved if requested object was inhumed.
+// Returns an error of type apistatus.ObjectNotFound if requested object is missing in local storage.
+// Returns an error of type apistatus.ObjectAlreadyRemoved if requested object was inhumed.
 //
 // Returns an error if executions are blocked (see BlockExecution).
 func (e *StorageEngine) Head(prm *HeadPrm) (res *HeadRes, err error) {

pkg/local_object_storage/engine/put.go

@@ -37,7 +37,7 @@ func (p *PutPrm) WithObject(obj *objectSDK.Object) *PutPrm {
 //
 // Returns an error if executions are blocked (see BlockExecution).
 //
-// Returns apistatus.ObjectAlreadyRemoved if object has been marked as removed.
+// Returns an error of type apistatus.ObjectAlreadyRemoved if object has been marked as removed.
 func (e *StorageEngine) Put(prm *PutPrm) (res *PutRes, err error) {
 	err = e.execIfNotBlocked(func() error {
 		res, err = e.put(prm)

pkg/local_object_storage/engine/range.go

@@ -59,8 +59,8 @@ func (r *RngRes) Object() *objectSDK.Object {
 // Returns any error encountered that
 // did not allow to completely read the object part.
 //
-// Returns apistatus.ObjectNotFound if requested object is missing in local storage.
-// Returns apistatus.ObjectAlreadyRemoved if requested object is inhumed.
+// Returns an error of type apistatus.ObjectNotFound if requested object is missing in local storage.
+// Returns an error of type apistatus.ObjectAlreadyRemoved if requested object is inhumed.
 // Returns ErrRangeOutOfBounds if requested object range is out of bounds.
 //
 // Returns an error if executions are blocked (see BlockExecution).

pkg/local_object_storage/metabase/exists.go

@@ -53,7 +53,7 @@ func Exists(db *DB, addr *addressSDK.Address) (bool, error) {
 // Exists returns ErrAlreadyRemoved if addr was marked as removed. Otherwise it
 // returns true if addr is in primary index or false if it is not.
 //
-// Returns apistatus.ObjectAlreadyRemoved if object has been placed in graveyard.
+// Returns an error of type apistatus.ObjectAlreadyRemoved if object has been placed in graveyard.
 func (db *DB) Exists(prm *ExistsPrm) (res *ExistsRes, err error) {
 	res = new(ExistsRes)
 

pkg/local_object_storage/metabase/get.go

@@ -70,8 +70,8 @@ func GetRaw(db *DB, addr *addressSDK.Address, raw bool) (*objectSDK.Object, erro
 
 // Get returns object header for specified address.
 //
-// Returns apistatus.ObjectNotFound if object is missing in DB.
-// Returns apistatus.ObjectAlreadyRemoved if object has been placed in graveyard.
+// Returns an error of type apistatus.ObjectNotFound if object is missing in DB.
+// Returns an error of type apistatus.ObjectAlreadyRemoved if object has been placed in graveyard.
 func (db *DB) Get(prm *GetPrm) (res *GetRes, err error) {
 	res = new(GetRes)
 

pkg/local_object_storage/metabase/put.go

@@ -70,7 +70,7 @@ func Put(db *DB, obj *objectSDK.Object, id *blobovnicza.ID) error {
 // Put saves object header in metabase. Object payload expected to be cut.
 // Big objects have nil blobovniczaID.
 //
-// Returns apistatus.ObjectAlreadyRemoved if object has been placed in graveyard.
+// Returns an error of type apistatus.ObjectAlreadyRemoved if object has been placed in graveyard.
 func (db *DB) Put(prm *PutPrm) (res *PutRes, err error) {
 	err = db.boltDB.Batch(func(tx *bbolt.Tx) error {
 		return db.put(tx, prm.obj, prm.id, nil)

pkg/local_object_storage/shard/exists.go

@@ -34,7 +34,7 @@ func (p *ExistsRes) Exists() bool {
 // Returns any error encountered that does not allow to
 // unambiguously determine the presence of an object.
 //
-// Returns apistatus.ObjectAlreadyRemoved if object has been marked as removed.
+// Returns an error of type apistatus.ObjectAlreadyRemoved if object has been marked as removed.
 func (s *Shard) Exists(prm *ExistsPrm) (*ExistsRes, error) {
 	exists, err := s.objectExists(prm.addr)
 

pkg/local_object_storage/shard/get.go

@@ -64,8 +64,8 @@ func (r *GetRes) HasMeta() bool {
 // Returns any error encountered that
 // did not allow to completely read the object part.
 //
-// Returns apistatus.ObjectNotFound if requested object is missing in shard.
-// Returns apistatus.ObjectAlreadyRemoved if requested object has been marked as removed in shard.
+// Returns an error of type apistatus.ObjectNotFound if requested object is missing in shard.
+// Returns an error of type apistatus.ObjectAlreadyRemoved if requested object has been marked as removed in shard.
 func (s *Shard) Get(prm *GetPrm) (*GetRes, error) {
 	var big, small storFetcher
 

pkg/local_object_storage/shard/head.go

@@ -51,8 +51,8 @@ func (r *HeadRes) Object() *objectSDK.Object {
 //
 // Returns any error encountered.
 //
-// Returns apistatus.ObjectNotFound if object is missing in Shard.
-// Returns apistatus.ObjectAlreadyRemoved if requested object has been marked as removed in shard.
+// Returns an error of type apistatus.ObjectNotFound if object is missing in Shard.
+// Returns an error of type apistatus.ObjectAlreadyRemoved if requested object has been marked as removed in shard.
 func (s *Shard) Head(prm *HeadPrm) (*HeadRes, error) {
 	// object can be saved in write-cache (if enabled) or in metabase
 

pkg/local_object_storage/shard/range.go

@@ -69,8 +69,8 @@ func (r *RngRes) HasMeta() bool {
 // did not allow to completely read the object part.
 //
 // Returns ErrRangeOutOfBounds if requested object range is out of bounds.
-// Returns apistatus.ObjectNotFound if requested object is missing.
-// Returns apistatus.ObjectAlreadyRemoved if requested object has been marked as removed in shard.
+// Returns an error of type apistatus.ObjectNotFound if requested object is missing.
+// Returns an error of type apistatus.ObjectAlreadyRemoved if requested object has been marked as removed in shard.
 func (s *Shard) GetRange(prm *RngPrm) (*RngRes, error) {
 	var big, small storFetcher
 

pkg/local_object_storage/writecache/delete.go

@@ -12,7 +12,7 @@ import (
 
 // Delete removes object from write-cache.
 //
-// Returns apistatus.ObjectNotFound is object is missing in write-cache.
+// Returns an error of type apistatus.ObjectNotFound if object is missing in write-cache.
 func (c *cache) Delete(addr *addressSDK.Address) error {
 	c.modeMtx.RLock()
 	defer c.modeMtx.RUnlock()

pkg/local_object_storage/writecache/get.go

@@ -9,7 +9,7 @@ import (
 
 // Get returns object from write-cache.
 //
-// Returns apistatus.ObjectNotFound if requested object is missing in write-cache.
+// Returns an error of type apistatus.ObjectNotFound if requested object is missing in write-cache.
 func (c *cache) Get(addr *addressSDK.Address) (*objectSDK.Object, error) {
 	saddr := addr.String()
 
@@ -48,7 +48,7 @@ func (c *cache) Get(addr *addressSDK.Address) (*objectSDK.Object, error) {
 
 // Head returns object header from write-cache.
 //
-// Returns apistatus.ObjectNotFound if requested object is missing in write-cache.
+// Returns an error of type apistatus.ObjectNotFound if requested object is missing in write-cache.
 func (c *cache) Head(addr *addressSDK.Address) (*objectSDK.Object, error) {
 	// TODO: #1149 easiest to implement solution is presented here, consider more efficient way, e.g.:
 	//  - provide header as common object.Object to Put, but marked to prevent correlation with full object
@@ -68,7 +68,7 @@ func (c *cache) Head(addr *addressSDK.Address) (*objectSDK.Object, error) {
 // Get fetches object from the underlying database.
 // Key should be a stringified address.
 //
-// Returns apistatus.ObjectNotFound if requested object is missing in db.
+// Returns an error of type apistatus.ObjectNotFound if requested object is missing in db.
 func Get(db *bbolt.DB, key []byte) ([]byte, error) {
 	var value []byte
 	err := db.View(func(tx *bbolt.Tx) error {