[#961] client: Clarify error returns in docs

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

cmd/neofs-cli/internal/client/client.go

@@ -34,6 +34,8 @@ func (x BalanceOfRes) Balance() *accounting.Decimal {
 }
 
 // BalanceOf requests current balance of NeoFS user.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func BalanceOf(prm BalanceOfPrm) (res BalanceOfRes, err error) {
 	res.cliRes, err = prm.cli.GetBalance(context.Background(), prm.ownerID,
 		client.WithKey(prm.privKey),
@@ -59,6 +61,8 @@ func (x ListContainersRes) IDList() []*cid.ID {
 }
 
 // ListContainers requests list of NeoFS user's containers.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func ListContainers(prm ListContainersPrm) (res ListContainersRes, err error) {
 	res.cliRes, err = prm.cli.ListContainers(context.Background(), prm.ownerID,
 		client.WithKey(prm.privKey),
@@ -96,6 +100,8 @@ func (x PutContainerRes) ID() *cid.ID {
 // The required time is also not predictable.
 //
 // Success can be verified by reading by identifier.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func PutContainer(prm PutContainerPrm) (res PutContainerRes, err error) {
 	res.cliRes, err = prm.cli.PutContainer(context.Background(), prm.cnr,
 		client.WithKey(prm.privKey),
@@ -122,6 +128,8 @@ func (x GetContainerRes) Container() *container.Container {
 }
 
 // GetContainer reads container from NeoFS by ID.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func GetContainer(prm GetContainerPrm) (res GetContainerRes, err error) {
 	res.cliRes, err = prm.cli.GetContainer(context.Background(), prm.cnrID,
 		client.WithKey(prm.privKey),
@@ -146,6 +154,8 @@ type DeleteContainerRes struct{}
 // The required time is also not predictable.
 //
 // Success can be verified by reading by identifier.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func DeleteContainer(prm DeleteContainerPrm) (res DeleteContainerRes, err error) {
 	err = prm.cli.DeleteContainer(context.Background(), prm.cnrID,
 		client.WithKey(prm.privKey),
@@ -172,6 +182,8 @@ func (x EACLRes) EACL() *eacl.Table {
 }
 
 // EACL reads eACL table from NeoFS by container ID.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func EACL(prm EACLPrm) (res EACLRes, err error) {
 	res.cliRes, err = prm.cli.GetEACL(context.Background(), prm.cnrID,
 		client.WithKey(prm.privKey),
@@ -202,6 +214,8 @@ type SetEACLRes struct{}
 // The required time is also not predictable.
 //
 // Success can be verified by reading by container identifier.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func SetEACL(prm SetEACLPrm) (res SetEACLRes, err error) {
 	err = prm.cli.SetEACL(context.Background(), prm.eaclTable,
 		client.WithKey(prm.privKey),
@@ -227,6 +241,8 @@ func (x NetworkInfoRes) NetworkInfo() *netmap.NetworkInfo {
 }
 
 // NetworkInfo reads information about the NeoFS network.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func NetworkInfo(prm NetworkInfoPrm) (res NetworkInfoRes, err error) {
 	res.cliRes, err = prm.cli.NetworkInfo(context.Background(),
 		client.WithKey(prm.privKey),
@@ -256,6 +272,8 @@ func (x NodeInfoRes) LatestVersion() *version.Version {
 }
 
 // NodeInfo requests information about the remote server from NeoFS netmap.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func NodeInfo(prm NodeInfoPrm) (res NodeInfoRes, err error) {
 	res.cliRes, err = prm.cli.EndpointInfo(context.Background(),
 		client.WithKey(prm.privKey),
@@ -285,6 +303,8 @@ func (x CreateSessionRes) SessionKey() []byte {
 }
 
 // CreateSession opens new unlimited session with the remote node.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func CreateSession(prm CreateSessionPrm) (res CreateSessionRes, err error) {
 	res.cliRes, err = prm.cli.CreateSession(context.Background(), math.MaxUint64,
 		client.WithKey(prm.privKey),
@@ -323,6 +343,8 @@ func (x PutObjectRes) ID() *object.ID {
 }
 
 // PutObject saves the object in NeoFS network.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func PutObject(prm PutObjectPrm) (res PutObjectRes, err error) {
 	var putPrm client.PutObjectParams
 
@@ -355,6 +377,8 @@ func (x DeleteObjectRes) TombstoneAddress() *object.Address {
 }
 
 // DeleteObject marks object to be removed from NeoFS through tombstone placement.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func DeleteObject(prm DeleteObjectPrm) (res DeleteObjectRes, err error) {
 	var delPrm client.DeleteObjectParams
 
@@ -390,6 +414,9 @@ func (x GetObjectRes) Header() *object.Object {
 // GetObject reads the object by address.
 //
 // Interrupts on any writer error. If successful, payload is written to writer.
+//
+// Returns any error prevented the operation from completing correctly in error return.
+// For raw reading, returns *object.SplitInfoError error if object is virtual.
 func GetObject(prm GetObjectPrm) (res GetObjectRes, err error) {
 	var getPrm client.GetObjectParams
 
@@ -432,6 +459,7 @@ func (x HeadObjectRes) Header() *object.Object {
 
 // HeadObject reads object header by address.
 //
+// Returns any error prevented the operation from completing correctly in error return.
 // For raw reading, returns *object.SplitInfoError error if object is virtual.
 func HeadObject(prm HeadObjectPrm) (res HeadObjectRes, err error) {
 	var cliPrm client.ObjectHeaderParams
@@ -478,6 +506,8 @@ func (x SearchObjectsRes) IDList() []*object.ID {
 }
 
 // SearchObjects selects objects from container which match the filters.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func SearchObjects(prm SearchObjectsPrm) (res SearchObjectsRes, err error) {
 	var cliPrm client.SearchObjectParams
 
@@ -532,6 +562,7 @@ func (x HashPayloadRangesRes) HashList() [][]byte {
 
 // HashPayloadRanges requests hashes (by default SHA256) of the object payload ranges.
 //
+// Returns any error prevented the operation from completing correctly in error return.
 // Returns an error if number of received hashes differs with the number of requested ranges.
 func HashPayloadRanges(prm HashPayloadRangesPrm) (res HashPayloadRangesRes, err error) {
 	var cliPrm client.RangeChecksumParams
@@ -596,6 +627,9 @@ type PayloadRangeRes struct{}
 // PayloadRange reads object payload range from NeoFS and writes it to specified writer.
 //
 // Interrupts on any writer error.
+//
+// Returns any error prevented the operation from completing correctly in error return.
+// For raw reading, returns *object.SplitInfoError error if object is virtual.
 func PayloadRange(prm PayloadRangePrm) (res PayloadRangeRes, err error) {
 	var cliPrm client.RangeDataParams
 

cmd/neofs-node/reputation/internal/client/client.go

@@ -62,6 +62,8 @@ type AnnounceLocalRes struct{}
 // AnnounceLocal sends estimations of local trust to the remote node.
 //
 // Client, context and key must be set.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func AnnounceLocal(prm AnnounceLocalPrm) (res AnnounceLocalRes, err error) {
 	_, err = prm.cli.AnnounceLocalTrust(prm.ctx, prm.cliPrm, prm.opts...)
 
@@ -97,6 +99,8 @@ type AnnounceIntermediateRes struct{}
 // and epoch to to the remote node.
 //
 // Client, context and key must be set.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func AnnounceIntermediate(prm AnnounceIntermediatePrm) (res AnnounceIntermediateRes, err error) {
 	_, err = prm.cli.AnnounceIntermediateTrust(prm.ctx, prm.cliPrm, prm.opts...)
 

pkg/innerring/internal/client/client.go

@@ -53,6 +53,8 @@ func (x SearchSGRes) IDList() []*object.ID {
 var sgFilter = storagegroup.SearchQuery()
 
 // SearchSG lists objects of storage group type in the container.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func (x Client) SearchSG(prm SearchSGPrm) (res SearchSGRes, err error) {
 	var cliPrm client.SearchObjectParams
 
@@ -82,6 +84,8 @@ func (x GetObjectRes) Object() *object.Object {
 }
 
 // GetObject reads the object by address.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func (x Client) GetObject(prm GetObjectPrm) (res GetObjectRes, err error) {
 	var cliPrm client.GetObjectParams
 
@@ -125,7 +129,8 @@ func (x HeadObjectRes) Header() *object.Object {
 
 // HeadObject reads short object header by address.
 //
-// For raw requests, returns an error if requested object is virtual.
+// Returns any error prevented the operation from completing correctly in error return.
+// For raw requests, returns *object.SplitInfoError error if requested object is virtual.
 func (x Client) HeadObject(prm HeadObjectPrm) (res HeadObjectRes, err error) {
 	var cliPrm client.ObjectHeaderParams
 
@@ -142,6 +147,8 @@ func (x Client) HeadObject(prm HeadObjectPrm) (res HeadObjectRes, err error) {
 }
 
 // GetObjectPayload reads object by address from NeoFS via Client and returns its payload.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func GetObjectPayload(ctx context.Context, c Client, addr *object.Address) ([]byte, error) {
 	var prm GetObjectPrm
 
@@ -210,6 +217,8 @@ func (x HashPayloadRangeRes) Hash() []byte {
 
 // HashObjectRange requests to calculate Tillich-Zemor hash of the payload range of the object
 // from the remote server's local storage.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func (x Client) HashPayloadRange(prm HashPayloadRangePrm) (res HashPayloadRangeRes, err error) {
 	var cliPrm client.RangeChecksumParams
 
@@ -233,6 +242,8 @@ func (x Client) HashPayloadRange(prm HashPayloadRangePrm) (res HashPayloadRangeR
 
 // HashObjectRange reads Tillich-Zemor hash of the object payload range by address
 // from the remote server's local storage via Client.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func HashObjectRange(ctx context.Context, c Client, addr *object.Address, rng *object.Range) ([]byte, error) {
 	var prm HashPayloadRangePrm
 

pkg/services/object/internal/client/client.go

@@ -124,12 +124,15 @@ func (x GetObjectRes) Object() *object.Object {
 //
 // Client, context and key must be set.
 //
+// Returns any error prevented the operation from completing correctly in error return.
 // Returns:
 //  error of type *object.SplitInfoError if object if raw flag is set and requested object is virtual;
 //  object.ErrAlreadyRemoved error if requested object is marked to be removed.
 func GetObject(prm GetObjectPrm) (res GetObjectRes, err error) {
 	res.cliRes, err = prm.cli.GetObject(prm.ctx, &prm.cliPrm, prm.opts...)
 
+	// FIXME: object.ErrAlreadyRemoved never returns
+
 	return
 }
 
@@ -168,12 +171,15 @@ func (x HeadObjectRes) Header() *object.Object {
 //
 // Client, context and key must be set.
 //
+// Returns any error prevented the operation from completing correctly in error return.
 // Returns:
 //  error of type *object.SplitInfoError if object if raw flag is set and requested object is virtual;
 //  object.ErrAlreadyRemoved error if requested object is marked to be removed.
 func HeadObject(prm HeadObjectPrm) (res HeadObjectRes, err error) {
 	res.cliRes, err = prm.cli.GetObjectHeader(prm.ctx, &prm.cliPrm, prm.opts...)
 
+	// FIXME: object.ErrAlreadyRemoved never returns
+
 	return
 }
 
@@ -219,12 +225,15 @@ func (x PayloadRangeRes) PayloadRange() []byte {
 //
 // Client, context and key must be set.
 //
+// Returns any error prevented the operation from completing correctly in error return.
 // Returns:
 //  error of type *object.SplitInfoError if object if raw flag is set and requested object is virtual;
 //  object.ErrAlreadyRemoved error if requested object is marked to be removed.
 func PayloadRange(prm PayloadRangePrm) (res PayloadRangeRes, err error) {
 	res.cliRes, err = prm.cli.ObjectPayloadRangeData(prm.ctx, &prm.cliPrm, prm.opts...)
 
+	// FIXME: object.ErrAlreadyRemoved never returns
+
 	return
 }
 
@@ -255,6 +264,8 @@ func (x PutObjectRes) ID() *object.ID {
 // PutObject saves the object in local storage of the remote node.
 //
 // Client, context and key must be set.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func PutObject(prm PutObjectPrm) (res PutObjectRes, err error) {
 	res.cliRes, err = prm.cli.PutObject(prm.ctx, &prm.cliPrm,
 		append(prm.opts, client.WithTTL(1))...,
@@ -293,6 +304,8 @@ func (x SearchObjectsRes) IDList() []*object.ID {
 }
 
 // SearchObjects selects objects from container which match the filters.
+//
+// Returns any error prevented the operation from completing correctly in error return.
 func SearchObjects(prm SearchObjectsPrm) (res SearchObjectsRes, err error) {
 	res.cliRes, err = prm.cli.SearchObject(prm.ctx, &prm.cliPrm, prm.opts...)