From 543291f8c568a6b982d2ee20e5cfe67b043748cf Mon Sep 17 00:00:00 2001 From: Pavel Karpy Date: Wed, 29 Dec 2021 16:55:29 +0300 Subject: [PATCH] [#111] client: Add comments to client's public methods Signed-off-by: Pavel Karpy --- client/accounting.go | 4 ++++ client/container.go | 26 +++++++++++++++++++++++++- client/netmap.go | 6 ++++++ client/object.go | 28 ++++++++++++++++++++++++++++ client/reputation.go | 8 ++++++++ client/session.go | 4 ++++ 6 files changed, 75 insertions(+), 1 deletion(-) diff --git a/client/accounting.go b/client/accounting.go index d6514e4..d1aa37d 100644 --- a/client/accounting.go +++ b/client/accounting.go @@ -26,6 +26,10 @@ func (x BalanceOfRes) Amount() *accounting.Decimal { return x.amount } +// GetBalance receives owner balance through NeoFS API call. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) GetBalance(ctx context.Context, owner *owner.ID, opts ...CallOption) (*BalanceOfRes, error) { // apply all available options callOptions := c.defaultCallOptions() diff --git a/client/container.go b/client/container.go index 643e79b..9c238ae 100644 --- a/client/container.go +++ b/client/container.go @@ -63,6 +63,10 @@ func (x *ContainerPutRes) setID(id *cid.ID) { x.id = id } +// PutContainer puts container through NeoFS API call. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) PutContainer(ctx context.Context, cnr *container.Container, opts ...CallOption) (*ContainerPutRes, error) { // apply all available options callOptions := c.defaultCallOptions() @@ -169,7 +173,8 @@ func (x *ContainerGetRes) setContainer(cnr *container.Container) { // GetContainer receives container structure through NeoFS API call. // -// Returns error if container structure is received but does not meet NeoFS API specification. +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) GetContainer(ctx context.Context, id *cid.ID, opts ...CallOption) (*ContainerGetRes, error) { // apply all available options callOptions := c.defaultCallOptions() @@ -246,6 +251,10 @@ func (x *ContainerListRes) setIDList(ids []*cid.ID) { x.ids = ids } +// ListContainers receives all owner's containers through NeoFS API call. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) ListContainers(ctx context.Context, ownerID *owner.ID, opts ...CallOption) (*ContainerListRes, error) { // apply all available options callOptions := c.defaultCallOptions() @@ -316,6 +325,10 @@ type ContainerDeleteRes struct { statusRes } +// DeleteContainer deletes specified container through NeoFS API call. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) DeleteContainer(ctx context.Context, id *cid.ID, opts ...CallOption) (*ContainerDeleteRes, error) { // apply all available options callOptions := c.defaultCallOptions() @@ -394,6 +407,10 @@ func (x *EACLRes) SetTable(table *eacl.Table) { x.table = table } +// EACL receives eACL of the specified container through NeoFS API call. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) EACL(ctx context.Context, id *cid.ID, opts ...CallOption) (*EACLRes, error) { // apply all available options callOptions := c.defaultCallOptions() @@ -460,6 +477,10 @@ type SetEACLRes struct { statusRes } +// SetEACL sets eACL through NeoFS API call. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) SetEACL(ctx context.Context, eacl *eacl.Table, opts ...CallOption) (*SetEACLRes, error) { // apply all available options callOptions := c.defaultCallOptions() @@ -530,6 +551,9 @@ type AnnounceSpaceRes struct { // AnnounceContainerUsedSpace used by storage nodes to estimate their container // sizes during lifetime. Use it only in storage node applications. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) AnnounceContainerUsedSpace( ctx context.Context, announce []container.UsedSpaceAnnouncement, diff --git a/client/netmap.go b/client/netmap.go index 48d1f49..5fc5fe1 100644 --- a/client/netmap.go +++ b/client/netmap.go @@ -47,6 +47,9 @@ func (x *EndpointInfoRes) setInfo(info *EndpointInfo) { // EndpointInfo returns attributes, address and public key of the node, specified // in client constructor via address or open connection. This can be used as a // health check to see if node is alive and responses to requests. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) EndpointInfo(ctx context.Context, opts ...CallOption) (*EndpointInfoRes, error) { // apply all available options callOptions := c.defaultCallOptions() @@ -116,6 +119,9 @@ func (x *NetworkInfoRes) setInfo(info *netmap.NetworkInfo) { } // NetworkInfo returns information about the NeoFS network of which the remote server is a part. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) NetworkInfo(ctx context.Context, opts ...CallOption) (*NetworkInfoRes, error) { // apply all available options callOptions := c.defaultCallOptions() diff --git a/client/object.go b/client/object.go index 6658ace..bbd6b38 100644 --- a/client/object.go +++ b/client/object.go @@ -197,6 +197,10 @@ func (x ObjectPutRes) ID() *object.ID { return x.id } +// PutObject puts object through NeoFS API call. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) PutObject(ctx context.Context, p *PutObjectParams, opts ...CallOption) (*ObjectPutRes, error) { callOpts := c.defaultCallOptions() @@ -369,6 +373,9 @@ func (x *ObjectDeleteRes) setTombstoneAddress(addr *object.Address) { // DeleteObject removes object by address. // // If target of tombstone address is not set, the address is ignored. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) DeleteObject(ctx context.Context, p *DeleteObjectParams, opts ...CallOption) (*ObjectDeleteRes, error) { callOpts := c.defaultCallOptions() @@ -591,6 +598,10 @@ func writeUnexpectedMessageTypeErr(res resCommon, val interface{}) { res.setStatus(st) } +// GetObject receives object through NeoFS API call. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) GetObject(ctx context.Context, p *GetObjectParams, opts ...CallOption) (*ObjectGetRes, error) { callOpts := c.defaultCallOptions() @@ -799,6 +810,10 @@ type ObjectHeadRes struct { objectRes } +// HeadObject receives object's header through NeoFS API call. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) HeadObject(ctx context.Context, p *ObjectHeaderParams, opts ...CallOption) (*ObjectHeadRes, error) { callOpts := c.defaultCallOptions() @@ -992,6 +1007,10 @@ func (x ObjectRangeRes) Data() []byte { return x.data } +// ObjectPayloadRangeData receives object's range payload data through NeoFS API call. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) ObjectPayloadRangeData(ctx context.Context, p *RangeDataParams, opts ...CallOption) (*ObjectRangeRes, error) { callOpts := c.defaultCallOptions() @@ -1179,6 +1198,11 @@ func (x ObjectRangeHashRes) Hashes() [][]byte { return x.hashes } +// HashObjectPayloadRanges receives range hash of the object +// payload data through NeoFS API call. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) HashObjectPayloadRanges(ctx context.Context, p *RangeChecksumParams, opts ...CallOption) (*ObjectRangeHashRes, error) { callOpts := c.defaultCallOptions() @@ -1304,6 +1328,10 @@ func (x ObjectSearchRes) IDList() []*object.ID { return x.ids } +// SearchObjects searches for the objects through NeoFS API call. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) SearchObjects(ctx context.Context, p *SearchObjectParams, opts ...CallOption) (*ObjectSearchRes, error) { callOpts := c.defaultCallOptions() diff --git a/client/reputation.go b/client/reputation.go index 26faf6e..c8cfbd8 100644 --- a/client/reputation.go +++ b/client/reputation.go @@ -42,6 +42,10 @@ type AnnounceLocalTrustRes struct { statusRes } +// AnnounceLocalTrust announces node's local trusts through NeoFS API call. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) AnnounceLocalTrust(ctx context.Context, prm AnnounceLocalTrustPrm, opts ...CallOption) (*AnnounceLocalTrustRes, error) { // apply all available options callOptions := c.defaultCallOptions() @@ -133,6 +137,10 @@ type AnnounceIntermediateTrustRes struct { statusRes } +// AnnounceIntermediateTrust announces node's intermediate trusts through NeoFS API call. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) AnnounceIntermediateTrust(ctx context.Context, prm AnnounceIntermediateTrustPrm, opts ...CallOption) (*AnnounceIntermediateTrustRes, error) { // apply all available options callOptions := c.defaultCallOptions() diff --git a/client/session.go b/client/session.go index f04286e..fe11009 100644 --- a/client/session.go +++ b/client/session.go @@ -38,6 +38,10 @@ func (x CreateSessionRes) SessionKey() []byte { return x.sessionKey } +// CreateSession creates session through NeoFS API call. +// +// Any client's internal or transport errors are returned as error, +// NeoFS status codes are included in the returned results. func (c *Client) CreateSession(ctx context.Context, expiration uint64, opts ...CallOption) (*CreateSessionRes, error) { // apply all available options callOptions := c.defaultCallOptions()