[#92] client: Add docs about status returns

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

client/accounting.go

@@ -43,6 +43,7 @@ func (x GetBalanceRes) Amount() *accounting.Decimal {
 
 // GetBalance requests current balance of the NeoFS account.
 //
+// Exactly one return value is non-nil. By default, server status is returned in res structure.
 // Any client's internal or transport errors are returned as `error`,
 // If WithNeoFSErrorParsing option has been provided, unsuccessful
 // NeoFS status codes are returned as `error`, otherwise, are included
@@ -51,8 +52,8 @@ func (x GetBalanceRes) Amount() *accounting.Decimal {
 // Immediately panics if parameters are set incorrectly (see GetBalancePrm docs).
 // Context is required and must not be nil. It is used for network communication.
 //
-// Exactly one return value is non-nil. Server status return is returned in GetBalanceRes.
+// Return statuses:
-// Reflects all internal errors in second return value (transport problems, response processing, etc.).
+//  - global (see Client docs).
 func (c *Client) GetBalance(ctx context.Context, prm GetBalancePrm) (*GetBalanceRes, error) {
 	switch {
 	case ctx == nil:

client/client.go

@@ -14,6 +14,16 @@ import (
 // Using the Client that has been created with new(Client)
 // expression (or just declaring a Client variable) is unsafe
 // and can lead to panic.
+//
+// Each method which produces a NeoFS API call may return a server response.
+// Status responses are returned in the result structure, and can be cast
+// to built-in error instance (or in the returned error if the client is
+// configured accordingly). Certain statuses can be checked using `apistatus`
+// and standard `errors` packages.
+// All possible responses are documented in methods, however, some may be
+// returned from all of them (pay attention to the presence of the pointer sign):
+//  - *apistatus.ServerInternal on internal server error;
+//  - *apistatus.SuccessDefaultV2 on default success.
 type Client struct {
 	raw *client.Client
 

client/container.go

@@ -55,6 +55,7 @@ func (x *ContainerPutRes) setID(id *cid.ID) {
 
 // PutContainer sends request to save container in NeoFS.
 //
+// Exactly one return value is non-nil. By default, server status is returned in res structure.
 // Any client's internal or transport errors are returned as `error`.
 // If WithNeoFSErrorParsing option has been provided, unsuccessful
 // NeoFS status codes are returned as `error`, otherwise, are included
@@ -68,8 +69,8 @@ func (x *ContainerPutRes) setID(id *cid.ID) {
 // Immediately panics if parameters are set incorrectly (see ContainerPutPrm docs).
 // Context is required and must not be nil. It is used for network communication.
 //
-// Exactly one return value is non-nil. Server status return is returned in ContainerPutRes.
+// Return statuses:
-// Reflects all internal errors in second return value (transport problems, response processing, etc.).
+//  - global (see Client docs).
 func (c *Client) PutContainer(ctx context.Context, prm ContainerPutPrm) (*ContainerPutRes, error) {
 	// check parameters
 	switch {
@@ -166,8 +167,9 @@ func (x *ContainerGetRes) setContainer(cnr *container.Container) {
 	x.cnr = cnr
 }
 
-// GetContainer reads NeoFS container from by ID.
+// GetContainer reads NeoFS container by ID.
 //
+// Exactly one return value is non-nil. By default, server status is returned in res structure.
 // Any client's internal or transport errors are returned as `error`.
 // If WithNeoFSErrorParsing option has been provided, unsuccessful
 // NeoFS status codes are returned as `error`, otherwise, are included
@@ -176,8 +178,8 @@ func (x *ContainerGetRes) setContainer(cnr *container.Container) {
 // Immediately panics if parameters are set incorrectly (see ContainerGetPrm docs).
 // Context is required and must not be nil. It is used for network communication.
 //
-// Exactly one return value is non-nil. Server status return is returned in ContainerGetRes.
+// Return statuses:
-// Reflects all internal errors in second return value (transport problems, response processing, etc.).
+//  - global (see Client docs).
 func (c *Client) GetContainer(ctx context.Context, prm ContainerGetPrm) (*ContainerGetRes, error) {
 	switch {
 	case ctx == nil:
@@ -267,6 +269,7 @@ func (x *ContainerListRes) setContainers(ids []*cid.ID) {
 
 // ListContainers requests identifiers of the account-owned containers.
 //
+// Exactly one return value is non-nil. By default, server status is returned in res structure.
 // Any client's internal or transport errors are returned as `error`.
 // If WithNeoFSErrorParsing option has been provided, unsuccessful
 // NeoFS status codes are returned as `error`, otherwise, are included
@@ -275,8 +278,8 @@ func (x *ContainerListRes) setContainers(ids []*cid.ID) {
 // Immediately panics if parameters are set incorrectly (see ContainerListPrm docs).
 // Context is required and must not be nil. It is used for network communication.
 //
-// Exactly one return value is non-nil. Server status return is returned in ContainerListRes.
+// Return statuses:
-// Reflects all internal errors in second return value (transport problems, response processing, etc.).
+//  - global (see Client docs).
 func (c *Client) ListContainers(ctx context.Context, prm ContainerListPrm) (*ContainerListRes, error) {
 	// check parameters
 	switch {
@@ -365,6 +368,7 @@ func (c delContainerSignWrapper) SignedDataSize() int {
 
 // DeleteContainer sends request to remove the NeoFS container.
 //
+// Exactly one return value is non-nil. By default, server status is returned in res structure.
 // Any client's internal or transport errors are returned as `error`.
 // If WithNeoFSErrorParsing option has been provided, unsuccessful
 // NeoFS status codes are returned as `error`, otherwise, are included
@@ -380,6 +384,9 @@ func (c delContainerSignWrapper) SignedDataSize() int {
 //
 // Exactly one return value is non-nil. Server status return is returned in ContainerDeleteRes.
 // Reflects all internal errors in second return value (transport problems, response processing, etc.).
+//
+// Return statuses:
+//  - global (see Client docs).
 func (c *Client) DeleteContainer(ctx context.Context, prm ContainerDeletePrm) (*ContainerDeleteRes, error) {
 	// check parameters
 	switch {
@@ -475,6 +482,7 @@ func (x *EACLRes) setTable(table *eacl.Table) {
 
 // EACL reads eACL table of the NeoFS container.
 //
+// Exactly one return value is non-nil. By default, server status is returned in res structure.
 // Any client's internal or transport errors are returned as `error`.
 // If WithNeoFSErrorParsing option has been provided, unsuccessful
 // NeoFS status codes are returned as `error`, otherwise, are included
@@ -483,8 +491,8 @@ func (x *EACLRes) setTable(table *eacl.Table) {
 // Immediately panics if parameters are set incorrectly (see EACLPrm docs).
 // Context is required and must not be nil. It is used for network communication.
 //
-// Exactly one return value is non-nil. Server status return is returned in EACLRes.
+// Return statuses:
-// Reflects all internal errors in second return value (transport problems, response processing, etc.).
+//  - global (see Client docs).
 func (c *Client) EACL(ctx context.Context, prm EACLPrm) (*EACLRes, error) {
 	// check parameters
 	switch {
@@ -564,6 +572,7 @@ type SetEACLRes struct {
 
 // SetEACL sends request to update eACL table of the NeoFS container.
 //
+// Exactly one return value is non-nil. By default, server status is returned in res structure.
 // Any client's internal or transport errors are returned as `error`.
 // If WithNeoFSErrorParsing option has been provided, unsuccessful
 // NeoFS status codes are returned as `error`, otherwise, are included
@@ -577,8 +586,8 @@ type SetEACLRes struct {
 // Immediately panics if parameters are set incorrectly (see SetEACLPrm docs).
 // Context is required and must not be nil. It is used for network communication.
 //
-// Exactly one return value is non-nil. Server status return is returned in ContainerDeleteRes.
+// Return statuses:
-// Reflects all internal errors in second return value (transport problems, response processing, etc.).
+//  - global (see Client docs).
 func (c *Client) SetEACL(ctx context.Context, prm SetEACLPrm) (*SetEACLRes, error) {
 	// check parameters
 	switch {
@@ -658,6 +667,7 @@ type AnnounceSpaceRes struct {
 
 // AnnounceContainerUsedSpace sends request to announce volume of the space used for the container objects.
 //
+// Exactly one return value is non-nil. By default, server status is returned in res structure.
 // Any client's internal or transport errors are returned as `error`.
 // If WithNeoFSErrorParsing option has been provided, unsuccessful
 // NeoFS status codes are returned as `error`, otherwise, are included
@@ -671,8 +681,8 @@ type AnnounceSpaceRes struct {
 // Immediately panics if parameters are set incorrectly (see AnnounceSpacePrm docs).
 // Context is required and must not be nil. It is used for network communication.
 //
-// Exactly one return value is non-nil. Server status return is returned in AnnounceSpaceRes.
+// Return statuses:
-// Reflects all internal errors in second return value (transport problems, response processing, etc.).
+//  - global (see Client docs).
 func (c *Client) AnnounceContainerUsedSpace(ctx context.Context, prm AnnounceSpacePrm) (*AnnounceSpaceRes, error) {
 	// check parameters
 	switch {

client/netmap.go

@@ -61,6 +61,9 @@ func (x *EndpointInfoRes) setNodeInfo(info *netmap.NodeInfo) {
 //
 // Exactly one return value is non-nil. Server status return is returned in EndpointInfoRes.
 // Reflects all internal errors in second return value (transport problems, response processing, etc.).
+//
+// Return statuses:
+//  - global (see Client docs).
 func (c *Client) EndpointInfo(ctx context.Context, _ EndpointInfoPrm) (*EndpointInfoRes, error) {
 	// check context
 	if ctx == nil {
@@ -136,6 +139,9 @@ func (x *NetworkInfoRes) setInfo(info *netmap.NetworkInfo) {
 //
 // Exactly one return value is non-nil. Server status return is returned in NetworkInfoRes.
 // Reflects all internal errors in second return value (transport problems, response processing, etc.).
+//
+// Return statuses:
+//  - global (see Client docs).
 func (c *Client) NetworkInfo(ctx context.Context, _ NetworkInfoPrm) (*NetworkInfoRes, error) {
 	// check context
 	if ctx == nil {

client/reputation.go

@@ -37,6 +37,7 @@ type AnnounceLocalTrustRes struct {
 
 // AnnounceLocalTrust sends client's trust values to the NeoFS network participants.
 //
+// Exactly one return value is non-nil. By default, server status is returned in res structure.
 // Any client's internal or transport errors are returned as `error`.
 // If WithNeoFSErrorParsing option has been provided, unsuccessful
 // NeoFS status codes are returned as `error`, otherwise, are included
@@ -45,8 +46,8 @@ type AnnounceLocalTrustRes struct {
 // Immediately panics if parameters are set incorrectly (see AnnounceLocalTrustPrm docs).
 // Context is required and must not be nil. It is used for network communication.
 //
-// Exactly one return value is non-nil. Server status return is returned in AnnounceLocalTrustRes.
+// Return statuses:
-// Reflects all internal errors in second return value (transport problems, response processing, etc.).
+//  - global (see Client docs).
 func (c *Client) AnnounceLocalTrust(ctx context.Context, prm AnnounceLocalTrustPrm) (*AnnounceLocalTrustRes, error) {
 	// check parameters
 	switch {
@@ -134,6 +135,7 @@ type AnnounceIntermediateTrustRes struct {
 // AnnounceIntermediateTrust sends global trust values calculated for the specified NeoFS network participants
 // at some stage of client's calculation algorithm.
 //
+// Exactly one return value is non-nil. By default, server status is returned in res structure.
 // Any client's internal or transport errors are returned as `error`.
 // If WithNeoFSErrorParsing option has been provided, unsuccessful
 // NeoFS status codes are returned as `error`, otherwise, are included
@@ -142,8 +144,8 @@ type AnnounceIntermediateTrustRes struct {
 // Immediately panics if parameters are set incorrectly (see AnnounceIntermediateTrustPrm docs).
 // Context is required and must not be nil. It is used for network communication.
 //
-// Exactly one return value is non-nil. Server status return is returned in AnnounceIntermediateTrustRes.
+// Return statuses:
-// Reflects all internal errors in second return value (transport problems, response processing, etc.).
+//  - global (see Client docs).
 func (c *Client) AnnounceIntermediateTrust(ctx context.Context, prm AnnounceIntermediateTrustPrm) (*AnnounceIntermediateTrustRes, error) {
 	// check parameters
 	switch {

client/session.go

@@ -52,6 +52,7 @@ func (x CreateSessionRes) PublicKey() []byte {
 // The session lifetime coincides with the server lifetime. Results can be written
 // to session token which can be later attached to the requests.
 //
+// Exactly one return value is non-nil. By default, server status is returned in res structure.
 // Any client's internal or transport errors are returned as `error`.
 // If WithNeoFSErrorParsing option has been provided, unsuccessful
 // NeoFS status codes are returned as `error`, otherwise, are included
@@ -60,8 +61,8 @@ func (x CreateSessionRes) PublicKey() []byte {
 // Immediately panics if parameters are set incorrectly (see CreateSessionPrm docs).
 // Context is required and must not be nil. It is used for network communication.
 //
-// Exactly one return value is non-nil. Server status return is returned in CreateSessionRes.
+// Return statuses:
-// Reflects all internal errors in second return value (transport problems, response processing, etc.).
+//  - global (see Client docs).
 func (c *Client) CreateSession(ctx context.Context, prm CreateSessionPrm) (*CreateSessionRes, error) {
 	// check context
 	if ctx == nil {