Document go code snippets as examples

accounting/doc.go

@@ -1,33 +1,7 @@
 /*
 Package accounting provides primitives to perform accounting operations in NeoFS.
 
-Decimal type provides functionality to process user balances. For example, when
-working with Fixed8 balance precision:
-
-	var dec accounting.Decimal
-	dec.SetValue(val)
-	dec.SetPrecision(8)
-
-Instances can be also used to process NeoFS API V2 protocol messages
-(see neo.fs.v2.accounting package in https://github.com/nspcc-dev/neofs-api).
-
-On client side:
-
-	import "github.com/nspcc-dev/neofs-api-go/v2/accounting"
-
-	var msg accounting.Decimal
-	dec.WriteToV2(&msg)
-
-	// send msg
-
-On server side:
-
-	// recv msg
-
-	var dec accounting.Decimal
-	dec.ReadFromV2(msg)
-
-	// process dec
+Decimal type provides functionality to process user balances.
 
 Using package types in an application is recommended to potentially work with
 different protocol versions with which these types are compatible.

accounting/example_test.go

@@ -0,0 +1,41 @@
+package accounting_test
+
+import (
+	apiGoAccounting "github.com/nspcc-dev/neofs-api-go/v2/accounting"
+	"github.com/nspcc-dev/neofs-sdk-go/accounting"
+)
+
+// Decimal type provides functionality to process user balances. For example, when
+// working with Fixed8 balance precision.
+func ExampleDecimal_SetValue() {
+	var val int64
+
+	var dec accounting.Decimal
+	dec.SetValue(val)
+	dec.SetPrecision(8)
+}
+
+// Instances can be also used to process NeoFS API V2 protocol messages
+// (see neo.fs.v2.accounting package in https://github.com/nspcc-dev/neofs-api) on client side.
+func ExampleDecimal_WriteToV2() {
+	// import apiGoAccounting "github.com/nspcc-dev/neofs-api-go/v2/accounting"
+
+	var dec accounting.Decimal
+	var msg apiGoAccounting.Decimal
+	dec.WriteToV2(&msg)
+
+	// send msg
+}
+
+// Instances can be also used to process NeoFS API V2 protocol messages
+// (see neo.fs.v2.accounting package in https://github.com/nspcc-dev/neofs-api) on server side.
+func ExampleDecimal_ReadFromV2() {
+	// import apiGoAccounting "github.com/nspcc-dev/neofs-api-go/v2/accounting"
+
+	var dec accounting.Decimal
+	var msg apiGoAccounting.Decimal
+
+	_ = dec.ReadFromV2(msg)
+
+	// send msg
+}

audit/doc.go

@@ -1,25 +1,6 @@
 /*
 Package audit provides features to process data audit in NeoFS system.
 
-Result type groups values which can be gathered during data audit process:
-
-	var res audit.Result
-	res.ForEpoch(32)
-	res.ForContainer(cnr)
-	// ...
-	res.Complete()
-
-Result instances can be stored in a binary format. On reporter side:
-
-	data := res.Marshal()
-	// send data
-
-On receiver side:
-
-	var res audit.Result
-	err := res.Unmarshal(data)
-	// ...
-
 Using package types in an application is recommended to potentially work with
 different protocol versions with which these types are compatible.
 */

audit/example_test.go

@@ -0,0 +1,36 @@
+package audit_test
+
+import (
+	"github.com/nspcc-dev/neofs-sdk-go/audit"
+	cid "github.com/nspcc-dev/neofs-sdk-go/container/id"
+)
+
+// Result type groups values which can be gathered during data audit process.
+func Example() {
+	var res audit.Result
+	var cnr cid.ID
+
+	res.ForEpoch(32)
+	res.ForContainer(cnr)
+	// ...
+	res.Complete()
+}
+
+// Result instances can be stored in a binary format on reporter side.
+func ExampleResult_Marshal() {
+	var res audit.Result
+	data := res.Marshal()
+	_ = data
+
+	// send data
+}
+
+// Result instances can be restored from a binary format on receiver side.
+func ExampleResult_Unmarshal() {
+	var data []byte
+
+	var res audit.Result
+	_ = res.Unmarshal(data)
+
+	// process result
+}

bearer/doc.go

@@ -4,28 +4,5 @@ Package bearer provides bearer token definition.
 Bearer token is attached to the object service requests, and it overwrites
 extended ACL of the container. Mainly it is used to provide access of private
 data for specific user. Therefore, it must be signed by owner of the container.
-
-Define bearer token by setting correct lifetime, extended ACL and owner ID of
-the user that will attach token to its requests.
-
-	var bearerToken bearer.Token
-	bearerToken.SetExpiration(500)
-	bearerToken.SetIssuedAt(10)
-	bearerToken.SetNotBefore(10)
-	bearerToken.SetEACL(eaclTable)
-	bearerToken.SetOwner(ownerID)
-
-Bearer token must be signed by owner of the container.
-
-	err := bearerToken.Sign(privateKey)
-
-Provide signed token in JSON or binary format to the request sender. Request
-sender can attach this bearer token to the object service requests:
-
-	import sdkClient "github.com/nspcc-dev/neofs-sdk-go/client"
-
-	var headParams sdkClient.PrmObjectHead
-	headParams.WithBearerToken(bearerToken)
-	response, err := client.ObjectHead(ctx, headParams)
 */
 package bearer

bearer/example_test.go

@@ -0,0 +1,68 @@
+package bearer_test
+
+import (
+	"context"
+
+	"github.com/nspcc-dev/neofs-sdk-go/bearer"
+	"github.com/nspcc-dev/neofs-sdk-go/client"
+	cid "github.com/nspcc-dev/neofs-sdk-go/container/id"
+	neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto"
+	"github.com/nspcc-dev/neofs-sdk-go/eacl"
+	oid "github.com/nspcc-dev/neofs-sdk-go/object/id"
+	"github.com/nspcc-dev/neofs-sdk-go/user"
+)
+
+// Define bearer token by setting correct lifetime, extended ACL and owner ID of
+// the user that will attach token to its requests.
+func Example() {
+	// import "github.com/nspcc-dev/neofs-sdk-go/eacl"
+	// import "github.com/nspcc-dev/neofs-sdk-go/user"
+
+	var bearerToken bearer.Token
+	var ownerID user.ID
+	var eaclTable eacl.Table
+
+	bearerToken.SetExp(500)
+	bearerToken.SetIat(10)
+	bearerToken.SetNbf(10)
+	bearerToken.SetEACLTable(eaclTable)
+	bearerToken.ForUser(ownerID)
+}
+
+// Bearer token must be signed by owner of the container.
+func ExampleToken_Sign() {
+	// import neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto"
+
+	var bearerToken bearer.Token
+	var signer neofscrypto.Signer
+
+	// signer initialization, bearerToken initialization, other steps ...
+
+	_ = bearerToken.Sign(signer)
+
+	// ...
+}
+
+// Provide signed token in JSON or binary format to the request sender. Request
+// sender can attach this bearer token to the object service requests.
+func ExampleToken_attachToRequest() {
+	// import "github.com/nspcc-dev/neofs-sdk-go/client"
+	// import "github.com/nspcc-dev/neofs-sdk-go/user"
+	// import oid "github.com/nspcc-dev/neofs-sdk-go/object/id"
+	// import cid "github.com/nspcc-dev/neofs-sdk-go/container/id"
+
+	var bearerToken bearer.Token
+	var sdkClient *client.Client
+	var signer user.Signer
+
+	// init bearerToken, sdkClient, signer, other steps ...
+
+	var headParams client.PrmObjectHead
+	headParams.WithBearerToken(bearerToken)
+	// ...
+
+	response, err := sdkClient.ObjectHead(context.Background(), cid.ID{}, oid.ID{}, signer, headParams)
+
+	_ = response
+	_ = err
+}

checksum/doc.go

@@ -2,15 +2,6 @@
 Package checksum provides primitives to work with checksums.
 
 Checksum is a basic type of data checksums.
-For example, calculating checksums:
-
-	// retrieving any payload for hashing
-
-	var sha256Sum Checksum
-	Calculate(&sha256Sum, SHA256, payload) // sha256Sum contains SHA256 hash of the payload
-
-	var tzSum Checksum
-	Calculate(&tzSum, TZ, payload) // tzSum contains TZ hash of the payload
 
 Using package types in an application is recommended to potentially work with
 different protocol versions with which these types are compatible.

checksum/example_test.go

@@ -13,7 +13,10 @@ func ExampleCalculate() {
 	payload := []byte{0, 1, 2, 3, 4, 5, 6}
 	var cs Checksum
 
+	// sha256Sum contains SHA256 hash of the payload
 	Calculate(&cs, SHA256, payload)
+
+	// tzSum contains TZ hash of the payload
 	Calculate(&cs, TZ, payload)
 }
 

client/doc.go

@@ -3,84 +3,5 @@ Package client provides NeoFS API client implementation.
 
 The main component is Client type. It is a virtual connection to the network
 and provides methods for executing operations on the server.
-
-Create client instance:
-
-	var prm client.PrmInit
-	prm.SetDefaultSigner(signer)
-	// ...
-
-	c, err := client.New(prm)
-
-Connect to the NeoFS server:
-
-	var prm client.PrmDial
-	prm.SetServerURI("localhost:8080")
-	prm.SetDefaultSigner(signer)
-	// ...
-
-	err := c.Dial(prm)
-	// ...
-
-Execute NeoFS operation on the server:
-
-	var prm client.PrmContainerPut
-	// ...
-
-	res, err := c.ContainerPut(context.Background(), cnr, prm)
-	err := c.Dial(dialPrm)
-	if err == nil {
-		err = apistatus.ErrFromStatus(res.Status())
-	}
-	// ...
-
-Consume custom service of the server:
-
-	syntax = "proto3";
-
-	service CustomService {
-		rpc CustomRPC(CustomRPCRequest) returns (CustomRPCResponse);
-	}
-
-	import "github.com/nspcc-dev/neofs-api-go/v2/rpc/client"
-	import "github.com/nspcc-dev/neofs-api-go/v2/rpc/common"
-
-	req := new(CustomRPCRequest)
-	// ...
-	resp := new(CustomRPCResponse)
-
-	err := c.ExecRaw(func(c *client.Client) error {
-		return client.SendUnary(c, common.CallMethodInfo{
-			Service: "CustomService",
-			Name:    "CustomRPC",
-		}, req, resp)
-	})
-	// ...
-
-Close the connection:
-
-	err := c.Close()
-	// ...
-
-Note that it's not allowed to override Client behaviour directly: the parameters
-for the all operations are write-only and the results of the all operations are
-read-only. To be able to override client behavior (e.g. for tests), abstract it
-with an interface:
-
-	import "github.com/nspcc-dev/neofs-sdk-go/client"
-
-	type NeoFSClient interface {
-		// Operations according to the application needs
-		CreateContainer(context.Context, container.Container) error
-		// ...
-	}
-
-	type client struct {
-		c *client.Client
-	}
-
-	func (x *client) CreateContainer(context.Context, container.Container) error {
-		// ...
-	}
 */
 package client