[#150] *: Write status-related docs

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

accounting/service.proto

@@ -16,6 +16,11 @@ import "session/types.proto";
 // accounts are possible, if both use the same token type.
 service AccountingService {
   // Returns the amount of funds in GAS token for the requested NeoFS account.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS):
+  // balance has been successfully read;
+  // - Common failures (SECTION_FAILURE_COMMON).
   rpc Balance (BalanceRequest) returns (BalanceResponse);
 }
 

container/service.proto

@@ -19,30 +19,65 @@ service ContainerService {
   // response immediately. After a new block is issued in sidechain, request is
   // verified by Inner Ring nodes. After one more block in sidechain, container
   // is added into smart contract storage.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS):
+  // request to save the container has been sent to the sidechain;
+  // - Common failures (SECTION_FAILURE_COMMON).
   rpc Put(PutRequest) returns (PutResponse);
 
   // `Delete` invokes `Container` smart contract's `Delete` method and returns
   // response immediately. After a new block is issued in sidechain, request is
   // verified by Inner Ring nodes. After one more block in sidechain, container
   // is added into smart contract storage.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS):
+  // request to remove the container has been sent to the sidechain;
+  // - Common failures (SECTION_FAILURE_COMMON).
   rpc Delete(DeleteRequest) returns (DeleteResponse);
 
   // Returns container structure from `Container` smart contract storage.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS):
+  // container has been successfully read;
+  // - Common failures (SECTION_FAILURE_COMMON).
   rpc Get(GetRequest) returns (GetResponse);
 
   // Returns all owner's containers from 'Container` smart contract' storage.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS):
+  // container list has been successfully read;
+  // - Common failures (SECTION_FAILURE_COMMON).
   rpc List(ListRequest) returns (ListResponse);
 
   // Invokes 'SetEACL' method of 'Container` smart contract and returns response
   // immediately. After one more block in sidechain, Extended ACL changes are
   // added into smart contract storage.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS):
+  // request to save container eACL has been sent to the sidechain;
+  // - Common failures (SECTION_FAILURE_COMMON).
   rpc SetExtendedACL(SetExtendedACLRequest) returns (SetExtendedACLResponse);
 
   // Returns Extended ACL table and signature from `Container` smart contract
   // storage.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS):
+  // container eACL has been successfully read;
+  // - Common failures (SECTION_FAILURE_COMMON).
   rpc GetExtendedACL(GetExtendedACLRequest) returns (GetExtendedACLResponse);
 
   // Announce container used space values for P2P synchronization.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS):
+  // estimation of used space has been successfully announced;
+  // - Common failures (SECTION_FAILURE_COMMON).
   rpc AnnounceUsedSpace(AnnounceUsedSpaceRequest) returns (AnnounceUsedSpaceResponse);
 }
 

netmap/service.proto

@@ -19,9 +19,19 @@ service NetmapService {
   // want to get recent information directly, or to talk to the node not yet
   // present in `Network Map` to find out what API version can be used for
   // further communication. Can also be used to check if node is up and running.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS):
+  // information about the server has been successfully read;
+  // - Common failures (SECTION_FAILURE_COMMON).
   rpc LocalNodeInfo (LocalNodeInfoRequest) returns (LocalNodeInfoResponse);
 
   // Read recent information about the NeoFS network.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS):
+  // information about the current network state has been successfully read;
+  // - Common failures (SECTION_FAILURE_COMMON).
   rpc NetworkInfo (NetworkInfoRequest) returns (NetworkInfoResponse);
 }
 

object/service.proto

@@ -18,6 +18,11 @@ service ObjectService {
   // messages, except the first one, carry payload chunks. Requested object can
   // be restored by concatenation of object message payload and all chunks
   // keeping receiving order.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS):
+  // object has been successfully read;
+  // - Common failures (SECTION_FAILURE_COMMON).
   rpc Get(GetRequest) returns (stream GetResponse);
 
   // Put the object into container. Request uses gRPC stream. First message
@@ -26,32 +31,62 @@ service ObjectService {
   // session package). Chunk messages are considered by server as a part of an
   // object payload. All messages, except first one, SHOULD be payload chunks.
   // Chunk messages SHOULD be sent in direct order of fragmentation.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS):
+  // object has been successfully saved in the container;
+  // - Common failures (SECTION_FAILURE_COMMON).
   rpc Put(stream PutRequest) returns (PutResponse);
 
   // Delete the object from a container. There is no immediate removal
   // guarantee. Object will be marked for removal and deleted eventually.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS):
+  // object has been successfully marked to be removed from the container;
+  // - Common failures (SECTION_FAILURE_COMMON).
   rpc Delete(DeleteRequest) returns (DeleteResponse);
 
   // Returns the object Headers without data payload. By default full header is
   // returned. If `main_only` request field is set, the short header with only
   // the very minimal information would be returned instead.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS):
+  // object header has been successfully read;
+  // - Common failures (SECTION_FAILURE_COMMON).
   rpc Head(HeadRequest) returns (HeadResponse);
 
   // Search objects in container. Search query allows to match by Object
   // Header's filed values. Please see the corresponding NeoFS Technical
   // Specification section for more details.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS):
+  // objects have been successfully selected;
+  // - Common failures (SECTION_FAILURE_COMMON).
   rpc Search(SearchRequest) returns (stream SearchResponse);
 
   // Get byte range of data payload. Range is set as an (offset, length) tuple.
   // Like in `Get` method, the response uses gRPC stream. Requested range can be
   // restored by concatenation of all received payload chunks keeping receiving
   // order.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS):
+  // data range of the object payload has been successfully read;
+  // - Common failures (SECTION_FAILURE_COMMON).
   rpc GetRange(GetRangeRequest) returns (stream GetRangeResponse);
 
   // Returns homomorphic or regular hash of object's payload range after
   // applying XOR operation with the provided `salt`. Ranges are set of (offset,
   // length) tuples. Hashes order in response corresponds to ranges order in
   // request. Note that hash is calculated for XORed data.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS):
+  // data range of the object payload has been successfully hashed;
+  // - Common failures (SECTION_FAILURE_COMMON).
   rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse);
 }
 

proto-docs/accounting.md

@@ -50,6 +50,11 @@ rpc Balance(BalanceRequest) returns (BalanceResponse);
 
 Returns the amount of funds in GAS token for the requested NeoFS account.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+balance has been successfully read;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | Balance | [BalanceRequest](#neo.fs.v2.accounting.BalanceRequest) | [BalanceResponse](#neo.fs.v2.accounting.BalanceResponse) |

proto-docs/container.md

@@ -84,6 +84,11 @@ response immediately. After a new block is issued in sidechain, request is
 verified by Inner Ring nodes. After one more block in sidechain, container
 is added into smart contract storage.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+request to save the container has been sent to the sidechain;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | Put | [PutRequest](#neo.fs.v2.container.PutRequest) | [PutResponse](#neo.fs.v2.container.PutResponse) |
@@ -94,6 +99,11 @@ response immediately. After a new block is issued in sidechain, request is
 verified by Inner Ring nodes. After one more block in sidechain, container
 is added into smart contract storage.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+request to remove the container has been sent to the sidechain;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | Delete | [DeleteRequest](#neo.fs.v2.container.DeleteRequest) | [DeleteResponse](#neo.fs.v2.container.DeleteResponse) |
@@ -101,6 +111,11 @@ is added into smart contract storage.
 
 Returns container structure from `Container` smart contract storage.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+container has been successfully read;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | Get | [GetRequest](#neo.fs.v2.container.GetRequest) | [GetResponse](#neo.fs.v2.container.GetResponse) |
@@ -108,6 +123,11 @@ Returns container structure from `Container` smart contract storage.
 
 Returns all owner's containers from 'Container` smart contract' storage.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+container list has been successfully read;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | List | [ListRequest](#neo.fs.v2.container.ListRequest) | [ListResponse](#neo.fs.v2.container.ListResponse) |
@@ -117,6 +137,11 @@ Invokes 'SetEACL' method of 'Container` smart contract and returns response
 immediately. After one more block in sidechain, Extended ACL changes are
 added into smart contract storage.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+request to save container eACL has been sent to the sidechain;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | SetExtendedACL | [SetExtendedACLRequest](#neo.fs.v2.container.SetExtendedACLRequest) | [SetExtendedACLResponse](#neo.fs.v2.container.SetExtendedACLResponse) |
@@ -125,6 +150,11 @@ added into smart contract storage.
 Returns Extended ACL table and signature from `Container` smart contract
 storage.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+container eACL has been successfully read;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | GetExtendedACL | [GetExtendedACLRequest](#neo.fs.v2.container.GetExtendedACLRequest) | [GetExtendedACLResponse](#neo.fs.v2.container.GetExtendedACLResponse) |
@@ -132,6 +162,11 @@ storage.
 
 Announce container used space values for P2P synchronization.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+estimation of used space has been successfully announced;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | AnnounceUsedSpace | [AnnounceUsedSpaceRequest](#neo.fs.v2.container.AnnounceUsedSpaceRequest) | [AnnounceUsedSpaceResponse](#neo.fs.v2.container.AnnounceUsedSpaceResponse) |

proto-docs/netmap.md

@@ -66,6 +66,11 @@ want to get recent information directly, or to talk to the node not yet
 present in `Network Map` to find out what API version can be used for
 further communication. Can also be used to check if node is up and running.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+information about the server has been successfully read;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | LocalNodeInfo | [LocalNodeInfoRequest](#neo.fs.v2.netmap.LocalNodeInfoRequest) | [LocalNodeInfoResponse](#neo.fs.v2.netmap.LocalNodeInfoResponse) |
@@ -73,6 +78,11 @@ further communication. Can also be used to check if node is up and running.
 
 Read recent information about the NeoFS network.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+information about the current network state has been successfully read;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | NetworkInfo | [NetworkInfoRequest](#neo.fs.v2.netmap.NetworkInfoRequest) | [NetworkInfoResponse](#neo.fs.v2.netmap.NetworkInfoResponse) |

proto-docs/object.md

@@ -92,6 +92,11 @@ messages, except the first one, carry payload chunks. Requested object can
 be restored by concatenation of object message payload and all chunks
 keeping receiving order.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+object has been successfully read;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | Get | [GetRequest](#neo.fs.v2.object.GetRequest) | [GetResponse](#neo.fs.v2.object.GetResponse) |
@@ -104,6 +109,11 @@ session package). Chunk messages are considered by server as a part of an
 object payload. All messages, except first one, SHOULD be payload chunks.
 Chunk messages SHOULD be sent in direct order of fragmentation.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+object has been successfully saved in the container;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | Put | [PutRequest](#neo.fs.v2.object.PutRequest) | [PutResponse](#neo.fs.v2.object.PutResponse) |
@@ -112,6 +122,11 @@ Chunk messages SHOULD be sent in direct order of fragmentation.
 Delete the object from a container. There is no immediate removal
 guarantee. Object will be marked for removal and deleted eventually.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+object has been successfully marked to be removed from the container;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | Delete | [DeleteRequest](#neo.fs.v2.object.DeleteRequest) | [DeleteResponse](#neo.fs.v2.object.DeleteResponse) |
@@ -121,6 +136,11 @@ Returns the object Headers without data payload. By default full header is
 returned. If `main_only` request field is set, the short header with only
 the very minimal information would be returned instead.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+object header has been successfully read;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | Head | [HeadRequest](#neo.fs.v2.object.HeadRequest) | [HeadResponse](#neo.fs.v2.object.HeadResponse) |
@@ -130,6 +150,11 @@ Search objects in container. Search query allows to match by Object
 Header's filed values. Please see the corresponding NeoFS Technical
 Specification section for more details.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+objects have been successfully selected;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | Search | [SearchRequest](#neo.fs.v2.object.SearchRequest) | [SearchResponse](#neo.fs.v2.object.SearchResponse) |
@@ -140,6 +165,11 @@ Like in `Get` method, the response uses gRPC stream. Requested range can be
 restored by concatenation of all received payload chunks keeping receiving
 order.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+data range of the object payload has been successfully read;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | GetRange | [GetRangeRequest](#neo.fs.v2.object.GetRangeRequest) | [GetRangeResponse](#neo.fs.v2.object.GetRangeResponse) |
@@ -150,6 +180,11 @@ applying XOR operation with the provided `salt`. Ranges are set of (offset,
 length) tuples. Hashes order in response corresponds to ranges order in
 request. Note that hash is calculated for XORed data.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+data range of the object payload has been successfully hashed;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | GetRangeHash | [GetRangeHashRequest](#neo.fs.v2.object.GetRangeHashRequest) | [GetRangeHashResponse](#neo.fs.v2.object.GetRangeHashResponse) |

proto-docs/reputation.md

@@ -59,6 +59,11 @@ rpc AnnounceIntermediateResult(AnnounceIntermediateResultRequest) returns (Annou
 
 Announce local client trust information to any node in NeoFS network.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+local trust has been successfully announced;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | AnnounceLocalTrust | [AnnounceLocalTrustRequest](#neo.fs.v2.reputation.AnnounceLocalTrustRequest) | [AnnounceLocalTrustResponse](#neo.fs.v2.reputation.AnnounceLocalTrustResponse) |
@@ -67,6 +72,11 @@ Announce local client trust information to any node in NeoFS network.
 Announces the intermediate result of the iterative algorithm for
 calculating the global reputation of the node in NeoFS network.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+intermediate trust estimation has been successfully announced;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | AnnounceIntermediateResult | [AnnounceIntermediateResultRequest](#neo.fs.v2.reputation.AnnounceIntermediateResultRequest) | [AnnounceIntermediateResultResponse](#neo.fs.v2.reputation.AnnounceIntermediateResultResponse) |

proto-docs/session.md

@@ -58,6 +58,11 @@ rpc Create(CreateRequest) returns (CreateResponse);
 
 Opens a new session between two peers.
 
+Statuses:
+- **OK** (0, SECTION_SUCCESS):
+session has been successfully opened;
+- Common failures (SECTION_FAILURE_COMMON).
+
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | Create | [CreateRequest](#neo.fs.v2.session.CreateRequest) | [CreateResponse](#neo.fs.v2.session.CreateResponse) |
@@ -198,6 +203,7 @@ Information about the response
 | ttl | [uint32](#uint32) |  | Maximum number of intermediate nodes in the request route |
 | x_headers | [XHeader](#neo.fs.v2.session.XHeader) | repeated | Response X-Headers |
 | origin | [ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) |  | `ResponseMetaHeader` of the origin request |
+| status | [neo.fs.v2.status.Status](#neo.fs.v2.status.Status) |  | Status return. |
 
 
 <a name="neo.fs.v2.session.ResponseVerificationHeader"></a>

proto-docs/status.md

@@ -0,0 +1,138 @@
+# Protocol Documentation
+<a name="top"></a>
+
+## Table of Contents
+
+- [status/types.proto](#status/types.proto)
+
+  - Messages
+    - [Status](#neo.fs.v2.status.Status)
+    - [Status.Detail](#neo.fs.v2.status.Status.Detail)
+    
+
+- [Scalar Value Types](#scalar-value-types)
+
+
+
+<a name="status/types.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## status/types.proto
+
+
+ <!-- end services -->
+
+
+<a name="neo.fs.v2.status.Status"></a>
+
+### Message Status
+Declares the general format of the status returns of the NeoFS RPC protocol.
+Status is present in all response messages. Each RPC of NeoFS protocol
+describes the possible outcomes and details of the operation.
+
+Each status is assigned a one-to-one numeric code. Any unique result of an
+operation in NeoFS is unambiguously associated with the code value.
+
+Numerical set of codes is split into 1024-element sections. An enumeration
+is defined for each section. Values can be referred to in the following ways:
+
+* numerical value ranging from 0 to 4,294,967,295 (global code);
+
+* values from enumeration (local code). The formula for the ratio of the
+  local code (`L`) of a defined section (`S`) to the global one (`G`):
+  `G = 1024 * S + L`.
+
+All outcomes are divided into successful and failed, which corresponds
+to the success or failure of the operation. The definition of success
+follows from the semantics of RPC and the description of its purpose.
+The server must not attach code that is the opposite of outcome type.
+
+See the set of return codes in the description for calls.
+
+Each status can carry developer-facing error message. It should be human
+readable text in English. The server should not transmit (and the client
+should not expect) useful information in the message. Field `details`
+should make the return more detailed.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| code | [uint32](#uint32) |  | The status code. |
+| message | [string](#string) |  | Developer-facing error message. |
+| details | [Status.Detail](#neo.fs.v2.status.Status.Detail) | repeated | Data detailing the outcome of the operation. Must be unique by ID. |
+
+
+<a name="neo.fs.v2.status.Status.Detail"></a>
+
+### Message Status.Detail
+Return detail. It contains additional information that can be used to
+analyze the response. Each code defines a set of details that can be
+attached to a status. Client should not handle details that are not
+covered by the code.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| id | [uint32](#uint32) |  | Detail ID. The identifier is required to determine the binary format of the detail and how to decode it. |
+| value | [bytes](#bytes) |  | Binary status detail. Must follow the format associated with ID. The possibility of missing a value must be explicitly allowed. |
+
+ <!-- end messages -->
+
+
+<a name="neo.fs.v2.status.CommonFail"></a>
+
+### CommonFail
+Section of failed statuses independent of the operation.
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| INTERNAL | 0 | [**1024**] Internal server error, default failure. Not detailed.. If the server cannot match failed outcome to the code , it should use this code. |
+
+
+
+<a name="neo.fs.v2.status.Section"></a>
+
+### Section
+Section identifiers.
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| SECTION_SUCCESS | 0 | Successful return codes. |
+| SECTION_FAILURE_COMMON | 1 | Failure codes regardless of the operation. |
+
+
+
+<a name="neo.fs.v2.status.Success"></a>
+
+### Success
+Section of NeoFS successful return codes.
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| OK | 0 | [**0**] Default success. Not detailed. If the server cannot match successful outcome to the code, it should use this code. |
+
+
+ <!-- end enums -->
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+| <a name="double" /> double |  | double | double | float |
+| <a name="float" /> float |  | float | float | float |
+| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
+| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
+| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
+| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
+| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
+| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
+| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
+| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
+| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
+| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
+| <a name="bool" /> bool |  | bool | boolean | boolean |
+| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
+| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
+

reputation/service.proto

@@ -15,10 +15,20 @@ import "session/types.proto";
 // final result is recorded.
 service ReputationService {
     // Announce local client trust information to any node in NeoFS network.
+    //
+    // Statuses:
+    // - **OK** (0, SECTION_SUCCESS):
+    // local trust has been successfully announced;
+    // - Common failures (SECTION_FAILURE_COMMON).
     rpc AnnounceLocalTrust (AnnounceLocalTrustRequest) returns (AnnounceLocalTrustResponse);
 
     // Announces the intermediate result of the iterative algorithm for
     // calculating the global reputation of the node in NeoFS network.
+    //
+    // Statuses:
+    // - **OK** (0, SECTION_SUCCESS):
+    // intermediate trust estimation has been successfully announced;
+    // - Common failures (SECTION_FAILURE_COMMON).
     rpc AnnounceIntermediateResult (AnnounceIntermediateResultRequest) returns (AnnounceIntermediateResultResponse);
 }
 

session/service.proto

@@ -14,6 +14,11 @@ import "session/types.proto";
 // section of NeoFS Technical Specification for details.
 service SessionService {
   // Opens a new session between two peers.
+  //
+  // Statuses:
+  // - **OK** (0, SECTION_SUCCESS):
+  // session has been successfully opened;
+  // - Common failures (SECTION_FAILURE_COMMON).
   rpc Create (CreateRequest) returns (CreateResponse);
 }
 

session/types.proto

@@ -186,6 +186,7 @@ message ResponseMetaHeader {
   // `ResponseMetaHeader` of the origin request
   ResponseMetaHeader origin = 5 [json_name = "origin"];
 
+  // Status return
   neo.fs.v2.status.Status status = 6 [json_name = "status"];
 }
 

status/types.proto

@@ -5,30 +5,79 @@ package neo.fs.v2.status;
 option go_package = "github.com/nspcc-dev/neofs-api-go/v2/status/grpc;status";
 option csharp_namespace = "Neo.FileStorage.API.Status";
 
+// Declares the general format of the status returns of the NeoFS RPC protocol.
+// Status is present in all response messages. Each RPC of NeoFS protocol
+// describes the possible outcomes and details of the operation.
+//
+// Each status is assigned a one-to-one numeric code. Any unique result of an
+// operation in NeoFS is unambiguously associated with the code value.
+//
+// Numerical set of codes is split into 1024-element sections. An enumeration
+// is defined for each section. Values can be referred to in the following ways:
+//
+// * numerical value ranging from 0 to 4,294,967,295 (global code);
+//
+// * values from enumeration (local code). The formula for the ratio of the
+//   local code (`L`) of a defined section (`S`) to the global one (`G`):
+//   `G = 1024 * S + L`.
+//
+// All outcomes are divided into successful and failed, which corresponds
+// to the success or failure of the operation. The definition of success
+// follows from the semantics of RPC and the description of its purpose.
+// The server must not attach code that is the opposite of outcome type.
+//
+// See the set of return codes in the description for calls.
+//
+// Each status can carry developer-facing error message. It should be human
+// readable text in English. The server should not transmit (and the client
+// should not expect) useful information in the message. Field `details`
+// should make the return more detailed.
 message Status {
+    // The status code
     uint32 code = 1;
 
+    // Developer-facing error message
     string message = 2;
 
+    // Return detail. It contains additional information that can be used to
+    // analyze the response. Each code defines a set of details that can be
+    // attached to a status. Client should not handle details that are not
+    // covered by the code.
     message Detail {
+        // Detail ID. The identifier is required to determine the binary format
+        // of the detail and how to decode it.
         uint32 id = 1;
 
+        // Binary status detail. Must follow the format associated with ID.
+        // The possibility of missing a value must be explicitly allowed.
         bytes value = 2;
     }
 
+    // Data detailing the outcome of the operation. Must be unique by ID.
     repeated Detail details = 3;
 }
 
+// Section identifiers.
+enum Section {
+    // Successful return codes.
+    SECTION_SUCCESS = 0;
+
+    // Failure codes regardless of the operation.
+    SECTION_FAILURE_COMMON = 1;
+}
+
+// Section of NeoFS successful return codes.
 enum Success {
+    // [**0**] Default success. Not detailed.
+    // If the server cannot match successful outcome to the code, it should
+    // use this code.
     OK = 0;
 }
 
+// Section of failed statuses independent of the operation.
 enum CommonFail {
+    // [**1024**] Internal server error, default failure. Not detailed.
+    // If the server cannot match failed outcome to the code, it should
+    // use this code.
     INTERNAL = 0;
 }
-
-enum Section {
-    SECTION_SUCCESS = 0;
-
-    SECTION_FAILURE_COMMON = 1;
-}