From 318639e5bf48a258d648cf1b5485153f35828d08 Mon Sep 17 00:00:00 2001
From: Leonard Lyubich <leonard@nspcc.ru>
Date: Thu, 17 Mar 2022 16:26:17 +0300
Subject: [PATCH] [#1247] *: Clarify docs about returned errors from
 `apistatus` 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                        | 2 +-
 pkg/innerring/rpc.go                                 | 2 +-
 pkg/innerring/settlement.go                          | 2 +-
 pkg/local_object_storage/blobovnicza/delete.go       | 2 +-
 pkg/local_object_storage/blobovnicza/get.go          | 2 +-
 pkg/local_object_storage/blobstor/delete_big.go      | 2 +-
 pkg/local_object_storage/blobstor/delete_small.go    | 2 +-
 pkg/local_object_storage/blobstor/get_big.go         | 2 +-
 pkg/local_object_storage/blobstor/get_range_big.go   | 2 +-
 pkg/local_object_storage/blobstor/get_range_small.go | 2 +-
 pkg/local_object_storage/blobstor/get_small.go       | 2 +-
 pkg/local_object_storage/engine/get.go               | 4 ++--
 pkg/local_object_storage/engine/head.go              | 4 ++--
 pkg/local_object_storage/engine/put.go               | 2 +-
 pkg/local_object_storage/engine/range.go             | 4 ++--
 pkg/local_object_storage/metabase/exists.go          | 2 +-
 pkg/local_object_storage/metabase/get.go             | 4 ++--
 pkg/local_object_storage/metabase/put.go             | 2 +-
 pkg/local_object_storage/shard/exists.go             | 2 +-
 pkg/local_object_storage/shard/get.go                | 4 ++--
 pkg/local_object_storage/shard/head.go               | 4 ++--
 pkg/local_object_storage/shard/range.go              | 4 ++--
 pkg/local_object_storage/writecache/delete.go        | 2 +-
 pkg/local_object_storage/writecache/get.go           | 6 +++---
 24 files changed, 33 insertions(+), 33 deletions(-)

diff --git a/pkg/core/container/storage.go b/pkg/core/container/storage.go
index 5f6f23d2f..3d8b87c2f 100644
--- a/pkg/core/container/storage.go
+++ b/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.
diff --git a/pkg/innerring/rpc.go b/pkg/innerring/rpc.go
index 8c2ddca3a..d02b5f2d8 100644
--- a/pkg/innerring/rpc.go
+++ b/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())
diff --git a/pkg/innerring/settlement.go b/pkg/innerring/settlement.go
index c317ec57c..c49ac1eef 100644
--- a/pkg/innerring/settlement.go
+++ b/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 {
diff --git a/pkg/local_object_storage/blobovnicza/delete.go b/pkg/local_object_storage/blobovnicza/delete.go
index e3a5eb0d7..3dd4cde7c 100644
--- a/pkg/local_object_storage/blobovnicza/delete.go
+++ b/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) {
diff --git a/pkg/local_object_storage/blobovnicza/get.go b/pkg/local_object_storage/blobovnicza/get.go
index 84dcb628c..10eb55b63 100644
--- a/pkg/local_object_storage/blobovnicza/get.go
+++ b/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 (
diff --git a/pkg/local_object_storage/blobstor/delete_big.go b/pkg/local_object_storage/blobstor/delete_big.go
index 83fa8a8cd..b3b500d36 100644
--- a/pkg/local_object_storage/blobstor/delete_big.go
+++ b/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) {
diff --git a/pkg/local_object_storage/blobstor/delete_small.go b/pkg/local_object_storage/blobstor/delete_small.go
index e43f41e81..7de368a7a 100644
--- a/pkg/local_object_storage/blobstor/delete_small.go
+++ b/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)
 }
diff --git a/pkg/local_object_storage/blobstor/get_big.go b/pkg/local_object_storage/blobstor/get_big.go
index 8403924af..450879d6f 100644
--- a/pkg/local_object_storage/blobstor/get_big.go
+++ b/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
diff --git a/pkg/local_object_storage/blobstor/get_range_big.go b/pkg/local_object_storage/blobstor/get_range_big.go
index d24509283..236b41cfb 100644
--- a/pkg/local_object_storage/blobstor/get_range_big.go
+++ b/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)
diff --git a/pkg/local_object_storage/blobstor/get_range_small.go b/pkg/local_object_storage/blobstor/get_range_small.go
index 1baa8c311..1b4eb1e3c 100644
--- a/pkg/local_object_storage/blobstor/get_range_small.go
+++ b/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)
 }
diff --git a/pkg/local_object_storage/blobstor/get_small.go b/pkg/local_object_storage/blobstor/get_small.go
index d2caec5f3..f906992af 100644
--- a/pkg/local_object_storage/blobstor/get_small.go
+++ b/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)
 }
diff --git a/pkg/local_object_storage/engine/get.go b/pkg/local_object_storage/engine/get.go
index 7edda40c9..3e0b13390 100644
--- a/pkg/local_object_storage/engine/get.go
+++ b/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) {
diff --git a/pkg/local_object_storage/engine/head.go b/pkg/local_object_storage/engine/head.go
index eb898a7cf..0a91a5ae8 100644
--- a/pkg/local_object_storage/engine/head.go
+++ b/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) {
diff --git a/pkg/local_object_storage/engine/put.go b/pkg/local_object_storage/engine/put.go
index a1597b5e3..ef6a01f2a 100644
--- a/pkg/local_object_storage/engine/put.go
+++ b/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)
diff --git a/pkg/local_object_storage/engine/range.go b/pkg/local_object_storage/engine/range.go
index a5d1deb79..992015b46 100644
--- a/pkg/local_object_storage/engine/range.go
+++ b/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).
diff --git a/pkg/local_object_storage/metabase/exists.go b/pkg/local_object_storage/metabase/exists.go
index 2642f1bc0..95162f52f 100644
--- a/pkg/local_object_storage/metabase/exists.go
+++ b/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)
 
diff --git a/pkg/local_object_storage/metabase/get.go b/pkg/local_object_storage/metabase/get.go
index f43748363..decc8d122 100644
--- a/pkg/local_object_storage/metabase/get.go
+++ b/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)
 
diff --git a/pkg/local_object_storage/metabase/put.go b/pkg/local_object_storage/metabase/put.go
index 9ed483947..b898e872d 100644
--- a/pkg/local_object_storage/metabase/put.go
+++ b/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)
diff --git a/pkg/local_object_storage/shard/exists.go b/pkg/local_object_storage/shard/exists.go
index b8473352a..488214231 100644
--- a/pkg/local_object_storage/shard/exists.go
+++ b/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)
 
diff --git a/pkg/local_object_storage/shard/get.go b/pkg/local_object_storage/shard/get.go
index bed17a1c0..b5648db29 100644
--- a/pkg/local_object_storage/shard/get.go
+++ b/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
 
diff --git a/pkg/local_object_storage/shard/head.go b/pkg/local_object_storage/shard/head.go
index 04348e6c4..d8761bfe3 100644
--- a/pkg/local_object_storage/shard/head.go
+++ b/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
 
diff --git a/pkg/local_object_storage/shard/range.go b/pkg/local_object_storage/shard/range.go
index 7fa095652..454916625 100644
--- a/pkg/local_object_storage/shard/range.go
+++ b/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
 
diff --git a/pkg/local_object_storage/writecache/delete.go b/pkg/local_object_storage/writecache/delete.go
index e843ebd9d..bfdeb46db 100644
--- a/pkg/local_object_storage/writecache/delete.go
+++ b/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()
diff --git a/pkg/local_object_storage/writecache/get.go b/pkg/local_object_storage/writecache/get.go
index a3351105f..2553fa9f1 100644
--- a/pkg/local_object_storage/writecache/get.go
+++ b/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 {