Update auto-generated docs

Signed-off-by: Stanislav Bogatyrev <stanislav@nspcc.ru>
2020-10-16 14:40:12 +03:00 · 2020-10-16 14:40:12 +03:00 · a6ecab41b8
commit a6ecab41b8
parent 095a6cb043
8 changed files with 433 additions and 298 deletions
--- a/proto-docs/accounting.md
+++ b/proto-docs/accounting.md
@ -35,8 +35,11 @@
 <a name="neo.fs.v2.accounting.AccountingService"></a>
 ### Service "neo.fs.v2.accounting.AccountingService"
-The service provides methods for obtaining information
+Accounting service provides methods for interaction with NeoFS sidechain via
-about the account balance in NeoFS system.
+other NeoFS nodes to get information about the account balance. Deposit and
 Withdraw operations can't be implemented here, as they require Mainnet NeoFS
 smart contract invocation. Transfer operations between internal NeoFS
 accounts are possible, if both use the same token type.
 ```
 rpc Balance(BalanceRequest) returns (BalanceResponse);
@ -45,7 +48,7 @@ rpc Balance(BalanceRequest) returns (BalanceResponse);
 #### Method Balance
-Returns the amount of funds for the requested NeoFS account.
+Returns the amount of funds in GAS token for the requested NeoFS account.
 | Name | Input | Output |
 | ---- | ----- | ------ |
@ -56,13 +59,7 @@ Returns the amount of funds for the requested NeoFS account.
 <a name="neo.fs.v2.accounting.BalanceRequest"></a>
 ### Message BalanceRequest
-Message defines the request body of Balance method.
+BalanceRequest message
 To indicate the account for which the balance is requested, it's identifier
 is used.
 To gain access to the requested information, the request body must be formed
 according to the requirements from the system specification.
 | Field | Type | Label | Description |
@ -75,20 +72,21 @@ according to the requirements from the system specification.
 <a name="neo.fs.v2.accounting.BalanceRequest.Body"></a>
 ### Message BalanceRequest.Body
-Request body
+To indicate the account for which the balance is requested, it's identifier
 is used. It can be any existing account in NeoFS sidechain `Balance` smart
 contract. If omitted, client implementation MUST set it to the request's
 signer `OwnerID`.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) |  | Carries user identifier in NeoFS system for which the balance is requested. |
+| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) |  | Valid user identifier in `OwnerID` format for which the balance is requested. Required field. |
 <a name="neo.fs.v2.accounting.BalanceResponse"></a>
 ### Message BalanceResponse
-Message defines the response body of Balance method.
+BalanceResponse message
 The amount of funds is calculated in decimal numbers.
 | Field | Type | Label | Description |
@ -101,12 +99,13 @@ The amount of funds is calculated in decimal numbers.
 <a name="neo.fs.v2.accounting.BalanceResponse.Body"></a>
 ### Message BalanceResponse.Body
-Request body
+The amount of funds in GAS token for the `OwnerID`'s account requested.
 Balance is `Decimal` format to avoid precision issues with rounding.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| balance | [Decimal](#neo.fs.v2.accounting.Decimal) |  | Carries the amount of funds on the account. |
+| balance | [Decimal](#neo.fs.v2.accounting.Decimal) |  | Amount of funds in GAS token for the requested account. |
 <!-- end messages -->
@ -126,13 +125,19 @@ Request body
 <a name="neo.fs.v2.accounting.Decimal"></a>
 ### Message Decimal
-Decimal represents the decimal numbers.
+Standard floating point data type can't be used in NeoFS due to inexactness
 of the result when doing lots of small number operations. To solve the lost
 precision issue, special `Decimal` format is used for monetary computations.
 Please see [The General Decimal Arithmetic
 Specification](http://speleotrove.com/decimal/) for detailed problem
 description.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| value | [int64](#int64) |  | value carries number value. |
+| value | [int64](#int64) |  | Number in smallest Token fractions. |
-| precision | [uint32](#uint32) |  | precision carries value precision. |
+| precision | [uint32](#uint32) |  | Precision value indicating how many smallest fractions can be in one integer. |
 <!-- end messages -->
--- a/proto-docs/acl.md
+++ b/proto-docs/acl.md
@ -31,7 +31,12 @@
 <a name="neo.fs.v2.acl.BearerToken"></a>
 ### Message BearerToken
-BearerToken has information about request ACL rules with limited lifetime
+BearerToken allows to attach signed Extended ACL rules to the request in
 `RequestMetaHeader`. If container's Basic ACL rules allow, the attached rule
 set will be checked instead of one attached to the container itself. Just
 like [JWT](https://jwt.io), it has a limited lifetime and scope, hence can be
 used in the similar use cases, like providing authorisation to externally
 authenticated party.
 | Field | Type | Label | Description |
@ -43,20 +48,22 @@ BearerToken has information about request ACL rules with limited lifetime
 <a name="neo.fs.v2.acl.BearerToken.Body"></a>
 ### Message BearerToken.Body
-Bearer Token body
+Bearer Token body structure contains Extended ACL table issued by container
 owner with additional information preventing token's abuse.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| eacl_table | [EACLTable](#neo.fs.v2.acl.EACLTable) |  | EACLTable carries table of extended ACL rules |
+| eacl_table | [EACLTable](#neo.fs.v2.acl.EACLTable) |  | Table of Extended ACL rules to use instead of the ones attached to the container |
-| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) |  | OwnerID carries identifier of the token owner |
+| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) |  | `OwnerID` to whom the token was issued. MUST match with the request originator's `OwnerID` |
 | lifetime | [BearerToken.Body.TokenLifetime](#neo.fs.v2.acl.BearerToken.Body.TokenLifetime) |  | Token expiration and valid time period parameters |
 <a name="neo.fs.v2.acl.BearerToken.Body.TokenLifetime"></a>
 ### Message BearerToken.Body.TokenLifetime
-Lifetime parameters of the token. Filed names taken from rfc7519.
+Lifetime parameters of the token. Filed names taken from
 [rfc7519](https://tools.ietf.org/html/rfc7519).
 | Field | Type | Label | Description |
@ -69,54 +76,58 @@ Lifetime parameters of the token. Filed names taken from rfc7519.
 <a name="neo.fs.v2.acl.EACLRecord"></a>
 ### Message EACLRecord
-EACLRecord groups information about extended ACL rule.
+Describes a single eACL rule.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| operation | [Operation](#neo.fs.v2.acl.Operation) |  | Operation carries type of operation. |
+| operation | [Operation](#neo.fs.v2.acl.Operation) |  | NeoFS request Verb to match |
-| action | [Action](#neo.fs.v2.acl.Action) |  | Action carries ACL target action. |
+| action | [Action](#neo.fs.v2.acl.Action) |  | Rule execution result. Either allows or denies access if filters match. |
-| filters | [EACLRecord.Filter](#neo.fs.v2.acl.EACLRecord.Filter) | repeated | filters carries set of filters. |
+| filters | [EACLRecord.Filter](#neo.fs.v2.acl.EACLRecord.Filter) | repeated | List of filters to match and see if rule is applicable |
-| targets | [EACLRecord.Target](#neo.fs.v2.acl.EACLRecord.Target) | repeated | targets carries information about extended ACL target list. |
+| targets | [EACLRecord.Target](#neo.fs.v2.acl.EACLRecord.Target) | repeated | List of target subjects to apply ACL rule to |
 <a name="neo.fs.v2.acl.EACLRecord.Filter"></a>
 ### Message EACLRecord.Filter
-Filter definition
+Filter to check particular properties of the request or object.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| header_type | [HeaderType](#neo.fs.v2.acl.HeaderType) |  | Header carries type of header. |
+| header_type | [HeaderType](#neo.fs.v2.acl.HeaderType) |  | Define if Object or Request header will be used |
-| match_type | [MatchType](#neo.fs.v2.acl.MatchType) |  | MatchType carries type of match. |
+| match_type | [MatchType](#neo.fs.v2.acl.MatchType) |  | Match operation type |
-| header_name | [string](#string) |  | header_name carries name of filtering header. |
+| header_name | [string](#string) |  | Name of the Header to use |
-| header_val | [string](#string) |  | header_val carries value of filtering header. |
+| header_val | [string](#string) |  | Expected Header Value or pattern to match |
 <a name="neo.fs.v2.acl.EACLRecord.Target"></a>
 ### Message EACLRecord.Target
-Information about extended ACL target.
+Target to apply ACL rule. Can be a subject's role class or a list of public
 keys to match.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| role | [Role](#neo.fs.v2.acl.Role) |  | target carries target of ACL rule. |
+| role | [Role](#neo.fs.v2.acl.Role) |  | Target subject's role class |
-| key_list | [bytes](#bytes) | repeated | key_list carries public keys of ACL target. |
+| key_list | [bytes](#bytes) | repeated | List of public keys to identify target subject |
 <a name="neo.fs.v2.acl.EACLTable"></a>
 ### Message EACLTable
-EACLRecord carries the information about extended ACL rules.
+Extended ACL rules table. Defined a list of ACL rules additionally to Basic
 ACL. Extended ACL rules can be attached to the container and can be updated
 or may be defined in `BearerToken` structure. Please see the corresponding
 NeoFS Technical Specification's section for detailed description.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) |  | eACL format version. Effectively the version of API library used to create eACL Table |
+| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) |  | eACL format version. Effectively the version of API library used to create eACL Table. |
-| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) |  | Carries identifier of the container that should use given access control rules. |
+| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) |  | Identifier of the container that should use given access control rules |
-| records | [EACLRecord](#neo.fs.v2.acl.EACLRecord) | repeated | Records carries list of extended ACL rule records. |
+| records | [EACLRecord](#neo.fs.v2.acl.EACLRecord) | repeated | List of Extended ACL rules |
 <!-- end messages -->
@ -124,11 +135,12 @@ EACLRecord carries the information about extended ACL rules.
 <a name="neo.fs.v2.acl.Action"></a>
 ### Action
-Action is an enumeration of EACL actions.
+Rule execution result action. Either allows or denies access if the rule's
 filters match.
 | Name | Number | Description |
 | ---- | ------ | ----------- |
-| ACTION_UNSPECIFIED | 0 | Unspecified action, default value. |
+| ACTION_UNSPECIFIED | 0 | Unspecified action, default value |
 | ALLOW | 1 | Allow action |
 | DENY | 2 | Deny action |
@ -137,7 +149,7 @@ Action is an enumeration of EACL actions.
 <a name="neo.fs.v2.acl.HeaderType"></a>
 ### HeaderType
-Header is an enumeration of filtering header types.
+Enumeration of possible sources of Headers to apply filters.
 | Name | Number | Description |
 | ---- | ------ | ----------- |
@ -163,11 +175,12 @@ MatchType is an enumeration of match types.
 <a name="neo.fs.v2.acl.Operation"></a>
 ### Operation
-Operation is an enumeration of operation types.
+Request's operation type to match if the rule is applicable to a particular
 request.
 | Name | Number | Description |
 | ---- | ------ | ----------- |
-| OPERATION_UNSPECIFIED | 0 | Unspecified operation, default value. |
+| OPERATION_UNSPECIFIED | 0 | Unspecified operation, default value |
 | GET | 1 | Get |
 | HEAD | 2 | Head |
 | PUT | 3 | Put |
@ -185,10 +198,10 @@ Target role of the access control rule in access control list.
 | Name | Number | Description |
 | ---- | ------ | ----------- |
-| ROLE_UNSPECIFIED | 0 | Unspecified role, default value. |
+| ROLE_UNSPECIFIED | 0 | Unspecified role, default value |
-| USER | 1 | User target rule is applied if sender is the owner of the container. |
+| USER | 1 | User target rule is applied if sender is the owner of the container |
-| SYSTEM | 2 | System target rule is applied if sender is the storage node within the container or inner ring node. |
+| SYSTEM | 2 | System target rule is applied if sender is the storage node within the container or inner ring node |
-| OTHERS | 3 | Others target rule is applied if sender is not user or system target. |
+| OTHERS | 3 | Others target rule is applied if sender is not user nor system target |
 <!-- end enums -->
--- a/proto-docs/container.md
+++ b/proto-docs/container.md
@ -56,8 +56,10 @@
 <a name="neo.fs.v2.container.ContainerService"></a>
 ### Service "neo.fs.v2.container.ContainerService"
-ContainerService provides API to access container smart-contract in morph chain
+`ContainerService` provides API to interact with `Container` smart contract
-via NeoFS node.
+in NeoFS sidechain via other NeoFS nodes. All of those actions can be done
 equivalently by directly issuing transactions and RPC calls to sidechain
 nodes.
 ```
 rpc Put(PutRequest) returns (PutResponse);
@ -71,52 +73,51 @@ rpc GetExtendedACL(GetExtendedACLRequest) returns (GetExtendedACLResponse);
 #### Method Put
-Put invokes 'Put' method in container smart-contract and returns
+`Put` invokes `Container` smart contract's `Put` method and returns
-response immediately. After new block in morph chain, request is verified
+response immediately. After a new block is issued in sidechain, request is
-by inner ring nodes. After one more block in morph chain, container
+verified by Inner Ring nodes. After one more block in sidechain, container
-added into smart-contract storage.
+is added into smart contract storage.
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | Put | [PutRequest](#neo.fs.v2.container.PutRequest) | [PutResponse](#neo.fs.v2.container.PutResponse) |
 #### Method Delete
-Delete invokes 'Delete' method in container smart-contract and returns
+`Delete` invokes `Container` smart contract's `Delete` method and returns
-response immediately. After new block in morph chain, request is verified
+response immediately. After a new block is issued in sidechain, request is
-by inner ring nodes. After one more block in morph chain, container
+verified by Inner Ring nodes. After one more block in sidechain, container
-removed from smart-contract storage.
+is added into smart contract storage.
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | Delete | [DeleteRequest](#neo.fs.v2.container.DeleteRequest) | [DeleteResponse](#neo.fs.v2.container.DeleteResponse) |
 #### Method Get
-Get returns container from container smart-contract storage.
+Returns container structure from `Container` smart contract storage.
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | Get | [GetRequest](#neo.fs.v2.container.GetRequest) | [GetResponse](#neo.fs.v2.container.GetResponse) |
 #### Method List
-List returns all owner's containers from container smart-contract
+Returns all owner's containers from 'Container` smart contract' storage.
 storage.
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | List | [ListRequest](#neo.fs.v2.container.ListRequest) | [ListResponse](#neo.fs.v2.container.ListResponse) |
 #### Method SetExtendedACL
-SetExtendedACL invokes 'SetEACL' method in container smart-contract and
+Invokes 'SetEACL' method of 'Container` smart contract and returns response
-returns response immediately. After new block in morph chain,
+immediately. After one more block in sidechain, Extended ACL changes are
-Extended ACL added into smart-contract storage.
+added into smart contract storage.
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | SetExtendedACL | [SetExtendedACLRequest](#neo.fs.v2.container.SetExtendedACLRequest) | [SetExtendedACLResponse](#neo.fs.v2.container.SetExtendedACLResponse) |
 #### Method GetExtendedACL
-GetExtendedACL returns Extended ACL table and signature from container
+Returns Extended ACL table and signature from `Container` smart contract
-smart-contract storage.
+storage.
 | Name | Input | Output |
 | ---- | ----- | ------ |
@ -140,20 +141,22 @@ Container removal request
 <a name="neo.fs.v2.container.DeleteRequest.Body"></a>
 ### Message DeleteRequest.Body
-Request body
+Container removal request body has a signed `ContainerID` as a proof of
 container owner's intent. The signature will be verified by `Container`
 smart contract, so signing algorithm must be supported by NeoVM.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) |  | container_id carries identifier of the container to delete from NeoFS. |
+| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) |  | Identifier of the container to delete from NeoFS |
-| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Signature of container id according to RFC-6979. |
+| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | `ContainerID` signed with the container owner's key according to RFC-6979 |
 <a name="neo.fs.v2.container.DeleteResponse"></a>
 ### Message DeleteResponse
-DeleteResponse is empty because delete operation is asynchronous and done
+`DeleteResponse` has an empty body because delete operation is asynchronous
-via consensus in inner ring nodes
+and done via consensus in Inner Ring nodes.
 | Field | Type | Label | Description |
@ -166,7 +169,8 @@ via consensus in inner ring nodes
 <a name="neo.fs.v2.container.DeleteResponse.Body"></a>
 ### Message DeleteResponse.Body
-Response body
+`DeleteResponse` has an empty body because delete operation is asynchronous
 and done via consensus in Inner Ring nodes.
@ -186,12 +190,12 @@ Get Extended ACL
 <a name="neo.fs.v2.container.GetExtendedACLRequest.Body"></a>
 ### Message GetExtendedACLRequest.Body
-Request body
+Get Extended ACL request body
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) |  | container_id carries identifier of the container that has Extended ACL. |
+| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) |  | Identifier of the container having Extended ACL |
 <a name="neo.fs.v2.container.GetExtendedACLResponse"></a>
@ -210,13 +214,15 @@ Get Extended ACL
 <a name="neo.fs.v2.container.GetExtendedACLResponse.Body"></a>
 ### Message GetExtendedACLResponse.Body
-Response body
+Get Extended ACL Response body can be empty if the requested container did
 not have Extended ACL Table attached or Extended ACL was not allowed at
 container creation.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| eacl | [neo.fs.v2.acl.EACLTable](#neo.fs.v2.acl.EACLTable) |  | Extended ACL that has been requested if it was set up. |
+| eacl | [neo.fs.v2.acl.EACLTable](#neo.fs.v2.acl.EACLTable) |  | Extended ACL requested, if available |
-| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Signature of stable-marshalled Extended ACL according to RFC-6979. |
+| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Signature of stable-marshalled Extended ACL according to RFC-6979 |
 <a name="neo.fs.v2.container.GetRequest"></a>
@ -235,12 +241,12 @@ Get container structure
 <a name="neo.fs.v2.container.GetRequest.Body"></a>
 ### Message GetRequest.Body
-Request body
+Get container structure request body.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) |  | container_id carries identifier of the container to get. |
+| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) |  | Identifier of the container to get |
 <a name="neo.fs.v2.container.GetResponse"></a>
@ -259,12 +265,13 @@ Get container structure
 <a name="neo.fs.v2.container.GetResponse.Body"></a>
 ### Message GetResponse.Body
-Response body
+Get container response body does not have container structure signature. It
 was already verified on container creation.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| container | [Container](#neo.fs.v2.container.Container) |  | Container that has been requested. |
+| container | [Container](#neo.fs.v2.container.Container) |  | Requested container structure |
 <a name="neo.fs.v2.container.ListRequest"></a>
@ -275,7 +282,7 @@ List containers
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| body | [ListRequest.Body](#neo.fs.v2.container.ListRequest.Body) |  | Body of list containers request message. |
+| body | [ListRequest.Body](#neo.fs.v2.container.ListRequest.Body) |  | Body of list containers request message |
 | meta_header | [neo.fs.v2.session.RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) |  | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
 | verify_header | [neo.fs.v2.session.RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) |  | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
@ -283,12 +290,12 @@ List containers
 <a name="neo.fs.v2.container.ListRequest.Body"></a>
 ### Message ListRequest.Body
-Request body
+List containers request body.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) |  | owner_id carries identifier of the container owner. |
+| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) |  | Identifier of the container owner |
 <a name="neo.fs.v2.container.ListResponse"></a>
@ -307,12 +314,12 @@ List containers
 <a name="neo.fs.v2.container.ListResponse.Body"></a>
 ### Message ListResponse.Body
-Response body
+List containers response body.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| container_ids | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | repeated | ContainerIDs carries list of identifiers of the containers that belong to the owner. |
+| container_ids | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | repeated | List of `ContainerID`s belonging to the requested `OwnerID` |
 <a name="neo.fs.v2.container.PutRequest"></a>
@ -331,13 +338,17 @@ New NeoFS Container creation request
 <a name="neo.fs.v2.container.PutRequest.Body"></a>
 ### Message PutRequest.Body
-Request body
+Container creation request has container structure's signature as a
 separate field. It's not stored in sidechain, just verified on container
 creation by `Container` smart contract. `ContainerID` is a SHA256 hash of
 the stable-marshalled container strucutre, hence there is no need for
 additional signature checks.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| container | [Container](#neo.fs.v2.container.Container) |  | Container to create in NeoFS. |
+| container | [Container](#neo.fs.v2.container.Container) |  | Container structure to register in NeoFS |
-| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Signature of stable-marshalled container according to RFC-6979. |
+| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Signature of a stable-marshalled container according to RFC-6979 |
 <a name="neo.fs.v2.container.PutResponse"></a>
@ -356,12 +367,15 @@ New NeoFS Container creation response
 <a name="neo.fs.v2.container.PutResponse.Body"></a>
 ### Message PutResponse.Body
-Response body
+Container put response body contains information about the newly registered
 container as seen by `Container` smart contract. `ContainerID` can be
 calculated beforehand from the container structure and compared to the one
 returned here to make sure everything was done as expected.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) |  | container_id carries identifier of the new container. |
+| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) |  | Unique identifier of the newly created container |
 <a name="neo.fs.v2.container.SetExtendedACLRequest"></a>
@ -380,13 +394,14 @@ Set Extended ACL
 <a name="neo.fs.v2.container.SetExtendedACLRequest.Body"></a>
 ### Message SetExtendedACLRequest.Body
-Request body
+Set Extended ACL request body does not have separate `ContainerID`
 reference. It will be taken from `EACLTable.container_id` field.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| eacl | [neo.fs.v2.acl.EACLTable](#neo.fs.v2.acl.EACLTable) |  | Extended ACL to set for the container. |
+| eacl | [neo.fs.v2.acl.EACLTable](#neo.fs.v2.acl.EACLTable) |  | Extended ACL table to set for container |
-| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Signature of stable-marshalled Extended ACL according to RFC-6979. |
+| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Signature of stable-marshalled Extended ACL table according to RFC-6979 |
 <a name="neo.fs.v2.container.SetExtendedACLResponse"></a>
@ -405,7 +420,9 @@ Set Extended ACL
 <a name="neo.fs.v2.container.SetExtendedACLResponse.Body"></a>
 ### Message SetExtendedACLResponse.Body
-Response body
+`SetExtendedACLResponse` has an empty body because the operation is
 asynchronous and update should be reflected in `Container` smart contract's
 storage after next block is issued in sidechain.
 <!-- end messages -->
@ -426,32 +443,40 @@ Response body
 <a name="neo.fs.v2.container.Container"></a>
 ### Message Container
-Container is a structure that defines object placement behaviour. Objects
+Container is a structure that defines object placement behaviour. Objects can
-can be stored only within containers. They define placement rule, attributes
+be stored only within containers. They define placement rule, attributes and
-and access control information. ID of the container is a 32 byte long
+access control information. ID of the container is a 32 byte long SHA256 hash
-SHA256 hash of stable-marshalled container message.
+of stable-marshalled container message.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) |  | Container format version. Effectively the version of API library used to create container |
+| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) |  | Container format version. Effectively the version of API library used to create container. |
-| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) |  | OwnerID carries identifier of the container owner. |
+| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) |  | Identifier of the container owner |
-| nonce | [bytes](#bytes) |  | Nonce is a 16 byte UUID, used to avoid collisions of container id. |
+| nonce | [bytes](#bytes) |  | Nonce is a 16 byte UUID, used to avoid collisions of container id |
-| basic_acl | [uint32](#uint32) |  | BasicACL contains access control rules for owner, system, others groups and permission bits for bearer token and Extended ACL. |
+| basic_acl | [uint32](#uint32) |  | `BasicACL` contains access control rules for owner, system, others groups and permission bits for `BearerToken` and `Extended ACL` |
-| attributes | [Container.Attribute](#neo.fs.v2.container.Container.Attribute) | repeated | Attributes define any immutable characteristics of container. |
+| attributes | [Container.Attribute](#neo.fs.v2.container.Container.Attribute) | repeated | Attributes represent immutable container's meta data |
-| placement_policy | [neo.fs.v2.netmap.PlacementPolicy](#neo.fs.v2.netmap.PlacementPolicy) |  | Placement policy for the object inside the container. |
+| placement_policy | [neo.fs.v2.netmap.PlacementPolicy](#neo.fs.v2.netmap.PlacementPolicy) |  | Placement policy for the object inside the container |
 <a name="neo.fs.v2.container.Container.Attribute"></a>
 ### Message Container.Attribute
-Attribute is a key-value pair of strings.
+`Attribute` is a user-defined Key-Value metadata pair attached to the
 container. Container attribute are immutable. They are set at container
 creation and cna never be added or updated.
 There are some "well-known" attributes affecting system behaviour:
 * Subnet \
  String ID of container's storage subnet. Container can be attached to
  only one subnet.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| key | [string](#string) |  | Key of immutable container attribute. |
+| key | [string](#string) |  | Attribute name key |
-| value | [string](#string) |  | Value of immutable container attribute. |
+| value | [string](#string) |  | Attribute value |
 <!-- end messages -->
--- a/proto-docs/netmap.md
+++ b/proto-docs/netmap.md
@ -40,7 +40,10 @@
 <a name="neo.fs.v2.netmap.NetmapService"></a>
 ### Service "neo.fs.v2.netmap.NetmapService"
-Methods to work with NetworkMap
+`NetmapService` provides methods to work with `Network Map` and information
 required to build it. The resulting `Network Map` is stored in sidechain
 `Netmap` smart contract, while related information can be obtained from other
 NeoFS nodes.
 ```
 rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse);
@ -49,7 +52,11 @@ rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse);
 #### Method LocalNodeInfo
-Return information about Node
+Get NodeInfo structure from the particular node directly. Node information
 can be taken from `Netmap` smart contract, but in some cases the one may
 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.
 | Name | Input | Output |
 | ---- | ----- | ------ |
@ -60,12 +67,12 @@ Return information about Node
 <a name="neo.fs.v2.netmap.LocalNodeInfoRequest"></a>
 ### Message LocalNodeInfoRequest
-Get NodeInfo from the particular node directly
+Get NodeInfo structure from the particular node directly
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| body | [LocalNodeInfoRequest.Body](#neo.fs.v2.netmap.LocalNodeInfoRequest.Body) |  | Body of the balance request message. |
+| body | [LocalNodeInfoRequest.Body](#neo.fs.v2.netmap.LocalNodeInfoRequest.Body) |  | Body of the LocalNodeInfo request message |
 | meta_header | [neo.fs.v2.session.RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) |  | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
 | verify_header | [neo.fs.v2.session.RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) |  | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
@ -73,14 +80,14 @@ Get NodeInfo from the particular node directly
 <a name="neo.fs.v2.netmap.LocalNodeInfoRequest.Body"></a>
 ### Message LocalNodeInfoRequest.Body
-Request body
+LocalNodeInfo request body is empty.
 <a name="neo.fs.v2.netmap.LocalNodeInfoResponse"></a>
 ### Message LocalNodeInfoResponse
-Local nod Info, including API Version in use
+Local Node Info, including API Version in use
 | Field | Type | Label | Description |
@ -93,13 +100,13 @@ Local nod Info, including API Version in use
 <a name="neo.fs.v2.netmap.LocalNodeInfoResponse.Body"></a>
 ### Message LocalNodeInfoResponse.Body
-Response body
+Local Node Info, including API Version in use.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) |  | API version in use |
+| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) |  | Latest NeoFS API version in use |
-| node_info | [NodeInfo](#neo.fs.v2.netmap.NodeInfo) |  | NodeInfo from node itself |
+| node_info | [NodeInfo](#neo.fs.v2.netmap.NodeInfo) |  | NodeInfo structure with recent information from node itself |
 <!-- end messages -->
@ -119,12 +126,13 @@ Response body
 <a name="neo.fs.v2.netmap.Filter"></a>
 ### Message Filter
-Filter
+Filter will return the subset of nodes from `NetworkMap` or another filter's
 results, that will satisfy filter's conditions.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| name | [string](#string) |  | Name of the filter or a reference to the named filter. '*' means application to the whole unfiltered NetworkMap At top level it's used as a filter name. At lower levels it's considered to be a reference to another named filter |
+| name | [string](#string) |  | Name of the filter or a reference to the named filter. '*' means application to the whole unfiltered NetworkMap. At top level it's used as a filter name. At lower levels it's considered to be a reference to another named filter |
 | key | [string](#string) |  | Key to filter |
 | op | [Operation](#neo.fs.v2.netmap.Operation) |  | Filtering operation |
 | value | [string](#string) |  | Value to match |
@ -148,26 +156,63 @@ NeoFS node description
 <a name="neo.fs.v2.netmap.NodeInfo.Attribute"></a>
 ### Message NodeInfo.Attribute
-Attributes of the NeoFS node.
+Administrator-defined Attributes of the NeoFS Storage Node.
 Node's attributes are mostly used during Storage Policy evaluation to
 calculate object's placement and find a set of nodes satisfying policy
 requirements. There are some "well-known" node attributes common to all the
 Storage Nodes in the network and used implicitly with default values if not
 explicitly set:
 * Capacity \
  Total available disk space in Gigabytes.
 * Price \
  Price in GAS tokens for storing one GB of data during one Epoch. In node
  attributes it's a string presenting floating point number with comma or
  point delimiter for decimal part. In the Network Map it will be saved as
  64-bit unsigned integer representing number of minimal token fractions.
 * Subnet \
  String ID of Node's storage subnet. There can be only one subnet served
  by the Storage Node.
 * Locode \
  Node's geographic location in
  [UN/LOCODE](https://www.unece.org/cefact/codesfortrade/codes_index.html)
  format approximated to the nearest point defined in standard.
 * Country \
  Country code in
  [ISO 3166-1_alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
  format. Calculated automatically from `Locode` attribute
 * Region \
  Country's administative subdivision where node is located. Calculated
  automatically from `Locode` attribute based on `SubDiv` field. Presented
  in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) format.
 * City \
  City, town, village or rural area name where node is located written
  without diacritics . Calculated automatically from `Locode` attribute.
 For detailed description of each well-known attribute please see the
 corresponding section in NeoFS Technical specification.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
 | key | [string](#string) |  | Key of the node attribute. |
 | value | [string](#string) |  | Value of the node attribute. |
-| parents | [string](#string) | repeated | Parent keys, if any Example: For City it can be Region or Country |
+| parents | [string](#string) | repeated | Parent keys, if any. For example for `City` it could be `Region` and `Country`. |
 <a name="neo.fs.v2.netmap.PlacementPolicy"></a>
 ### Message PlacementPolicy
-Set of rules to select a subset of nodes able to store container's objects
+Set of rules to select a subset of nodes from `NetworkMap` able to store
 container's objects. The format is simple enough to transpile from different
 storage policy definition languages.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| replicas | [Replica](#neo.fs.v2.netmap.Replica) | repeated | Rules to set number of object replicas and place each one into a particular bucket |
+| replicas | [Replica](#neo.fs.v2.netmap.Replica) | repeated | Rules to set number of object replicas and place each one into a named bucket |
-| container_backup_factor | [uint32](#uint32) |  | Container backup factor controls how deep NeoFS will search for nodes alternatives to include into container. |
+| container_backup_factor | [uint32](#uint32) |  | Container backup factor controls how deep NeoFS will search for nodes alternatives to include into container's nodes subset |
 | selectors | [Selector](#neo.fs.v2.netmap.Selector) | repeated | Set of Selectors to form the container's nodes subset |
 | filters | [Filter](#neo.fs.v2.netmap.Filter) | repeated | List of named filters to reference in selectors |
@ -175,25 +220,28 @@ Set of rules to select a subset of nodes able to store container's objects
 <a name="neo.fs.v2.netmap.Replica"></a>
 ### Message Replica
-Exact bucket for each replica
+Number of object replicas in a set of nodes from the defined selector. If no
 selector set the root bucket containing all possible nodes will be used by
 default.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
 | count | [uint32](#uint32) |  | How many object replicas to put |
-| selector | [string](#string) |  | Named selector bucket to put in |
+| selector | [string](#string) |  | Named selector bucket to put replicas |
 <a name="neo.fs.v2.netmap.Selector"></a>
 ### Message Selector
-Selector
+Selector chooses a number of nodes from the bucket taking the nearest nodes
 to the provided `ContainerID` by hash distance.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
 | name | [string](#string) |  | Selector name to reference in object placement section |
-| count | [uint32](#uint32) |  | How many nodes to select from bucket |
+| count | [uint32](#uint32) |  | How many nodes to select from the bucket |
 | clause | [Clause](#neo.fs.v2.netmap.Clause) |  | Selector modifier showing how to form a bucket |
 | attribute | [string](#string) |  | Attribute bucket to select from |
 | filter | [string](#string) |  | Filter reference to select from |
@ -204,13 +252,13 @@ Selector
 <a name="neo.fs.v2.netmap.Clause"></a>
 ### Clause
-Selector modifier showing how the node set will be formed
+Selector modifier shows how the node set will be formed. By default selector
-By default selector just groups by attribute into a bucket selecting nodes
+just groups nodes into a bucket by attribute, selecting nodes only by their
-only by their hash distance.
+hash distance.
 | Name | Number | Description |
 | ---- | ------ | ----------- |
-| CLAUSE_UNSPECIFIED | 0 | No modifier defined |
+| CLAUSE_UNSPECIFIED | 0 | No modifier defined. Will select nodes from bucket randomly. |
 | SAME | 1 | SAME will select only nodes having the same value of bucket attribute |
 | DISTINCT | 2 | DISTINCT will select nodes having different values of bucket attribute |
--- a/proto-docs/object.md
+++ b/proto-docs/object.md
@ -68,7 +68,8 @@
 <a name="neo.fs.v2.object.ObjectService"></a>
 ### Service "neo.fs.v2.object.ObjectService"
-Object service provides API for manipulating with the object.
+`ObjectService` provides API for manipulating objects. Object operations do
 not interact with sidechain and are only served by nodes in p2p style.
 ```
 rpc Get(GetRequest) returns (stream GetResponse);
@ -83,11 +84,12 @@ rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse);
 #### Method Get
-Get the object from container. Response uses gRPC stream. First response
+Receive full object structure, including Headers and payload. Response uses
-message carry object of requested address. Chunk messages are parts of
+gRPC stream. First response message carries object with requested address.
-the object's payload if it is needed. All messages except first carry
+Chunk messages are parts of the object's payload if it is needed. All
-chunks. Requested object can be restored by concatenation of object
+messages, except the first one, carry payload chunks. Requested object can
-message payload and all chunks keeping receiving order.
+be restored by concatenation of object message payload and all chunks
 keeping receiving order.
 | Name | Input | Output |
 | ---- | ----- | ------ |
@ -95,55 +97,57 @@ message payload and all chunks keeping receiving order.
 #### Method Put
 Put the object into container. Request uses gRPC stream. First message
-SHOULD BE type of PutHeader. Container id and Owner id of object SHOULD
+SHOULD be of PutHeader type. `ContainerID` and `OwnerID` of an object
-BE set. Session token SHOULD BE obtained before put operation (see
+SHOULD be set. Session token SHOULD be obtained before `PUT` operation (see
-session package). Chunk messages considered by server as part of object
+session package). Chunk messages are considered by server as a part of an
-payload. All messages except first SHOULD BE chunks. Chunk messages
+object payload. All messages, except first one, SHOULD be payload chunks.
-SHOULD BE sent in direct order of fragmentation.
+Chunk messages SHOULD be sent in direct order of fragmentation.
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | Put | [PutRequest](#neo.fs.v2.object.PutRequest) | [PutResponse](#neo.fs.v2.object.PutResponse) |
 #### Method Delete
-Delete the object from a container
+Delete the object from a container. There is no immediate removal
 guarantee. Object will be marked for removal and deleted eventually.
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | Delete | [DeleteRequest](#neo.fs.v2.object.DeleteRequest) | [DeleteResponse](#neo.fs.v2.object.DeleteResponse) |
 #### Method Head
-Head returns the object without data payload. Object in the
+Returns the object Headers without data payload. By default full header is
-response has system header only. If full headers flag is set, extended
+returned. If `main_only` request field is set, the short header with only
-headers are also present.
+the very minimal information would be returned instead.
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | Head | [HeadRequest](#neo.fs.v2.object.HeadRequest) | [HeadResponse](#neo.fs.v2.object.HeadResponse) |
 #### Method Search
-Search objects in container. Version of query language format SHOULD BE
+Search objects in container. Search query allows to match by Object
-set to 1. Search query represented in serialized format (see query
+Header's filed values. Please see the corresponding NeoFS Technical
-package).
+Specification section for more details.
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | Search | [SearchRequest](#neo.fs.v2.object.SearchRequest) | [SearchResponse](#neo.fs.v2.object.SearchResponse) |
 #### Method GetRange
-GetRange of data payload. Range is a pair (offset, length).
+Get byte range of data payload. Range is set as an (offset, length) tuple.
-Requested range can be restored by concatenation of all chunks
+Like in `Get` method, the response uses gRPC stream. Requested range can be
-keeping receiving order.
+restored by concatenation of all received payload chunks keeping receiving
 order.
 | Name | Input | Output |
 | ---- | ----- | ------ |
 | GetRange | [GetRangeRequest](#neo.fs.v2.object.GetRangeRequest) | [GetRangeResponse](#neo.fs.v2.object.GetRangeResponse) |
 #### Method GetRangeHash
-GetRangeHash returns homomorphic hash of object payload range after XOR
+Returns homomorphic or regular hash of object's payload range after
-operation. Ranges are set of pairs (offset, length). Hashes order in
+applying XOR operation with the provided `salt`. Ranges are set of (offset,
-response corresponds to ranges order in request. Homomorphic hash is
+length) tuples. Hashes order in response corresponds to ranges order in
-calculated for XORed data.
+request. Note that hash is calculated for XORed data.
 | Name | Input | Output |
 | ---- | ----- | ------ |
@ -154,7 +158,7 @@ calculated for XORed data.
 <a name="neo.fs.v2.object.DeleteRequest"></a>
 ### Message DeleteRequest
-Object Delete request
+Object DELETE request
 | Field | Type | Label | Description |
@ -167,19 +171,19 @@ Object Delete request
 <a name="neo.fs.v2.object.DeleteRequest.Body"></a>
 ### Message DeleteRequest.Body
-Request body
+Object DELETE request body
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) |  | Carries the address of the object to be deleted. |
+| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) |  | Address of the object to be deleted |
 <a name="neo.fs.v2.object.DeleteResponse"></a>
 ### Message DeleteResponse
-DeleteResponse is empty because we cannot guarantee permanent object removal
+DeleteResponse body is empty because we cannot guarantee permanent object
-in distributed system.
+removal in distributed system.
 | Field | Type | Label | Description |
@ -192,7 +196,7 @@ in distributed system.
 <a name="neo.fs.v2.object.DeleteResponse.Body"></a>
 ### Message DeleteResponse.Body
-Response body
+Object DELETE Response has an empty body.
@ -212,14 +216,14 @@ Get hash of object's payload part
 <a name="neo.fs.v2.object.GetRangeHashRequest.Body"></a>
 ### Message GetRangeHashRequest.Body
-Request body
+Get hash of object's payload part request body.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) |  | Carries address of the object that contains the requested payload range. |
+| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) |  | Address of the object that containing the requested payload range |
-| ranges | [Range](#neo.fs.v2.object.Range) | repeated | Carries the list of object payload range to calculate homomorphic hash. |
+| ranges | [Range](#neo.fs.v2.object.Range) | repeated | List of object's payload ranges to calculate homomorphic hash |
-| salt | [bytes](#bytes) |  | Carries binary salt to XOR object payload ranges before hash calculation. |
+| salt | [bytes](#bytes) |  | Binary salt to XOR object's payload ranges before hash calculation |
 | type | [neo.fs.v2.refs.ChecksumType](#neo.fs.v2.refs.ChecksumType) |  | Checksum algorithm type |
@ -239,19 +243,19 @@ Get hash of object's payload part
 <a name="neo.fs.v2.object.GetRangeHashResponse.Body"></a>
 ### Message GetRangeHashResponse.Body
-Response body
+Get hash of object's payload part response body.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
 | type | [neo.fs.v2.refs.ChecksumType](#neo.fs.v2.refs.ChecksumType) |  | Checksum algorithm type |
-| hash_list | [bytes](#bytes) | repeated | List of range hashes in a binary format. |
+| hash_list | [bytes](#bytes) | repeated | List of range hashes in a binary format |
 <a name="neo.fs.v2.object.GetRangeRequest"></a>
 ### Message GetRangeRequest
-Request to get part of object's payload
+Request part of object's payload
 | Field | Type | Label | Description |
@ -264,13 +268,13 @@ Request to get part of object's payload
 <a name="neo.fs.v2.object.GetRangeRequest.Body"></a>
 ### Message GetRangeRequest.Body
-Request Body
+Byte range of object's payload request body
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) |  | Address carries address of the object that contains the requested payload range. |
+| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) |  | Address of the object containing the requested payload range |
-| range | [Range](#neo.fs.v2.object.Range) |  | Range carries the parameters of the requested payload range. |
+| range | [Range](#neo.fs.v2.object.Range) |  | Requested payload range |
 <a name="neo.fs.v2.object.GetRangeResponse"></a>
@ -289,18 +293,21 @@ Get part of object's payload
 <a name="neo.fs.v2.object.GetRangeResponse.Body"></a>
 ### Message GetRangeResponse.Body
-Response body
+Get Range response body uses streams to transfer the response. Because
 object payload considered a byte sequence, there is no need to have some
 initial preamble message. The requested byte range is sent as a series
 chunks.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| chunk | [bytes](#bytes) |  | Carries part of the object payload. |
+| chunk | [bytes](#bytes) |  | Chunked object payload's range |
 <a name="neo.fs.v2.object.GetRequest"></a>
 ### Message GetRequest
-Get object request
+GET object request
 | Field | Type | Label | Description |
@ -313,19 +320,19 @@ Get object request
 <a name="neo.fs.v2.object.GetRequest.Body"></a>
 ### Message GetRequest.Body
-Request body
+GET Object request body
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) |  | Address of the requested object. |
+| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) |  | Address of the requested object |
-| raw | [bool](#bool) |  | Carries the raw option flag of the request. Raw request is sent to receive only the objects that are physically stored on the server. |
+| raw | [bool](#bool) |  | If `raw` flag is set, request will work only with objects that are physically stored on the peer node |
 <a name="neo.fs.v2.object.GetResponse"></a>
 ### Message GetResponse
-get object response
+GET object response
 | Field | Type | Label | Description |
@ -338,32 +345,33 @@ get object response
 <a name="neo.fs.v2.object.GetResponse.Body"></a>
 ### Message GetResponse.Body
-Response body
+GET Object Response body
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| init | [GetResponse.Body.Init](#neo.fs.v2.object.GetResponse.Body.Init) |  | Initialization parameters of the object stream. |
+| init | [GetResponse.Body.Init](#neo.fs.v2.object.GetResponse.Body.Init) |  | Initial part of the object stream |
-| chunk | [bytes](#bytes) |  | Part of the object payload. |
+| chunk | [bytes](#bytes) |  | Chunked object payload |
 <a name="neo.fs.v2.object.GetResponse.Body.Init"></a>
 ### Message GetResponse.Body.Init
-Initialization parameters of the object got from NeoFS.
+Initial part of the `Object` structure stream. Technically it's a
 set of all `Object` structure's fields except `payload`.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | Object ID |
+| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | Object's unique identifier. |
-| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Object signature |
+| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Signed `ObjectID` |
-| header | [Header](#neo.fs.v2.object.Header) |  | Object header. |
+| header | [Header](#neo.fs.v2.object.Header) |  | Object metadata headers |
 <a name="neo.fs.v2.object.HeadRequest"></a>
 ### Message HeadRequest
-Object head request
+Object HEAD request
 | Field | Type | Label | Description |
@ -376,20 +384,20 @@ Object head request
 <a name="neo.fs.v2.object.HeadRequest.Body"></a>
 ### Message HeadRequest.Body
-Request body
+Object HEAD request body
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) |  | Address of the object with the requested header. |
+| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) |  | Address of the object with the requested Header |
 | main_only | [bool](#bool) |  | Return only minimal header subset |
-| raw | [bool](#bool) |  | Carries the raw option flag of the request. Raw request is sent to receive only the headers of the objects that are physically stored on the server. |
+| raw | [bool](#bool) |  | If `raw` flag is set, request will work only with objects that are physically stored on the peer node |
 <a name="neo.fs.v2.object.HeadResponse"></a>
 ### Message HeadResponse
-Head response
+Object HEAD response
 | Field | Type | Label | Description |
@ -402,31 +410,37 @@ Head response
 <a name="neo.fs.v2.object.HeadResponse.Body"></a>
 ### Message HeadResponse.Body
-Response body
+Object HEAD response body
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| header | [HeaderWithSignature](#neo.fs.v2.object.HeaderWithSignature) |  | Full object header with object ID signature |
+| header | [HeaderWithSignature](#neo.fs.v2.object.HeaderWithSignature) |  | Full object's `Header` with `ObjectID` signature |
 | short_header | [ShortHeader](#neo.fs.v2.object.ShortHeader) |  | Short object header |
 <a name="neo.fs.v2.object.HeaderWithSignature"></a>
 ### Message HeaderWithSignature
-Tuple of full object header and signature of object ID.
+Tuple of full object header and signature of `ObjectID`. \
 Signed `ObjectID` is present to verify full header's authenticity through the
 following steps:
 1. Calculate `SHA-256` of marshalled `Header` structure
 2. Check if the resulting hash matched `ObjectID`
 3. Check if `ObjectID` signature in `signature` field is correct
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
 | header | [Header](#neo.fs.v2.object.Header) |  | Full object header |
-| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Signed object_id to verify full header's authenticity through following steps: 1. Calculate SHA-256 of marshalled Headers structure. 2. Check if the resulting hash matched ObjectID 3. Check if ObjectID's signature in signature field is correct. |
+| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Signed `ObjectID` to verify full header's authenticity |
 <a name="neo.fs.v2.object.PutRequest"></a>
 ### Message PutRequest
-Put object request
+PUT object request
 | Field | Type | Label | Description |
@ -439,33 +453,34 @@ Put object request
 <a name="neo.fs.v2.object.PutRequest.Body"></a>
 ### Message PutRequest.Body
-Request body
+PUT request body
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| init | [PutRequest.Body.Init](#neo.fs.v2.object.PutRequest.Body.Init) |  | Carries the initialization parameters of the object stream. |
+| init | [PutRequest.Body.Init](#neo.fs.v2.object.PutRequest.Body.Init) |  | Initial part of the object stream |
-| chunk | [bytes](#bytes) |  | Carries part of the object payload. |
+| chunk | [bytes](#bytes) |  | Chunked object payload |
 <a name="neo.fs.v2.object.PutRequest.Body.Init"></a>
 ### Message PutRequest.Body.Init
-Groups initialization parameters of object placement in NeoFS.
+Newly created object structure parameters. If some optional parameters
 are not set, they will be calculated by a peer node.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | Object ID, where available |
+| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | ObjectID if available. |
-| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Object signature, were available |
+| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Object signature if available |
-| header | [Header](#neo.fs.v2.object.Header) |  | Header of the object to save in the system. |
+| header | [Header](#neo.fs.v2.object.Header) |  | Object's Header |
-| copies_number | [uint32](#uint32) |  | Number of the object copies to store within the RPC call. Default zero value is processed according to the container placement rules. |
+| copies_number | [uint32](#uint32) |  | Number of the object copies to store within the RPC call. By default object is processed according to the container's placement policy. |
 <a name="neo.fs.v2.object.PutResponse"></a>
 ### Message PutResponse
-Put object response
+PUT Object response
 | Field | Type | Label | Description |
@ -478,30 +493,30 @@ Put object response
 <a name="neo.fs.v2.object.PutResponse.Body"></a>
 ### Message PutResponse.Body
-Response body
+PUT Object response body
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | Carries identifier of the saved object. It is used to access an object in the container. |
+| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | Identifier of the saved object |
 <a name="neo.fs.v2.object.Range"></a>
 ### Message Range
-Range groups the parameters of object payload range.
+Object payload range.Ranges of zero length SHOULD be considered as invalid.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| offset | [uint64](#uint64) |  | Carries the offset of the range from the object payload start. |
+| offset | [uint64](#uint64) |  | Offset of the range from the object payload start |
-| length | [uint64](#uint64) |  | Carries the length of the object payload range. |
+| length | [uint64](#uint64) |  | Length in bytes of the object payload range |
 <a name="neo.fs.v2.object.SearchRequest"></a>
 ### Message SearchRequest
-Search objects request
+Object Search request
 | Field | Type | Label | Description |
@ -514,12 +529,12 @@ Search objects request
 <a name="neo.fs.v2.object.SearchRequest.Body"></a>
 ### Message SearchRequest.Body
-Request body
+Object Search request body
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) |  | Carries search container identifier. |
+| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) |  | Container identifier were to search |
 | version | [uint32](#uint32) |  | Version of the Query Language used |
 | filters | [SearchRequest.Body.Filter](#neo.fs.v2.object.SearchRequest.Body.Filter) | repeated | List of search expressions |
@ -553,12 +568,12 @@ Search response
 <a name="neo.fs.v2.object.SearchResponse.Body"></a>
 ### Message SearchResponse.Body
-Response body
+Object Search response body
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| id_list | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Carries list of object identifiers that match the search query |
+| id_list | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of `ObjectID`s that match the search query |
 <!-- end messages -->
@ -578,7 +593,7 @@ Response body
 <a name="neo.fs.v2.object.Header"></a>
 ### Message Header
-Object Headers
+Object Header
 | Field | Type | Label | Description |
@ -587,19 +602,29 @@ Object Headers
 | container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) |  | Object's container |
 | owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) |  | Object's owner |
 | creation_epoch | [uint64](#uint64) |  | Object creation Epoch |
-| payload_length | [uint64](#uint64) |  | Size of payload in bytes. 0xFFFFFFFFFFFFFFFF means `payload_length` is unknown |
+| payload_length | [uint64](#uint64) |  | Size of payload in bytes. `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown |
 | payload_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) |  | Hash of payload bytes |
-| object_type | [ObjectType](#neo.fs.v2.object.ObjectType) |  | Special object type |
+| object_type | [ObjectType](#neo.fs.v2.object.ObjectType) |  | Type of the object payload content |
 | homomorphic_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) |  | Homomorphic hash of the object payload. |
 | session_token | [neo.fs.v2.session.SessionToken](#neo.fs.v2.session.SessionToken) |  | Session token, if it was used during Object creation. Need it to verify integrity and authenticity out of Request scope. |
 | attributes | [Header.Attribute](#neo.fs.v2.object.Header.Attribute) | repeated | User-defined object attributes |
-| split | [Header.Split](#neo.fs.v2.object.Header.Split) |  | Position of the object in the split hierarchy. |
+| split | [Header.Split](#neo.fs.v2.object.Header.Split) |  | Position of the object in the split hierarchy |
 <a name="neo.fs.v2.object.Header.Attribute"></a>
 ### Message Header.Attribute
-Attribute groups the user-defined Key-Value pairs attached to the object
+`Attribute` is a user-defined Key-Value metadata pair attached to the
 object.
 There are some "well-known" attributes starting with `__NEOFS__` prefix
 that affect system behaviour:
 * __NEOFS__UPLOAD_ID
 * __NEOFS__EXPIRATION_EPOCH
 For detailed description of each well-known attribute please see the
 corresponding section in NeoFS Technical specification.
 | Field | Type | Label | Description |
@ -611,27 +636,32 @@ Attribute groups the user-defined Key-Value pairs attached to the object
 <a name="neo.fs.v2.object.Header.Split"></a>
 ### Message Header.Split
-Information about spawning the objects through a payload splitting.
+Bigger objects can be split into a chain of smaller objects. Information
 about inter-dependencies between spawned objects and how to re-construct
 the original one is in the `Split` headers. Parent and children objects
 must be within the same container.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| parent | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | Identifier of the origin object. Parent and children objects must be within the same container. Parent object_id is known only to the minor child. |
+| parent | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | Identifier of the origin object. Known only to the minor child. |
-| previous | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | Previous carries identifier of the left split neighbor. |
+| previous | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | Identifier of the left split neighbor |
 | parent_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | `signature` field of the parent object. Used to reconstruct parent. |
 | parent_header | [Header](#neo.fs.v2.object.Header) |  | `header` field of the parent object. Used to reconstruct parent. |
-| children | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Children carries list of identifiers of the objects generated by splitting the current. |
+| children | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of identifiers of the objects generated by splitting current one. |
 <a name="neo.fs.v2.object.Object"></a>
 ### Message Object
-Object structure.
+Object structure. Object is immutable and content-addressed. It means
 `ObjectID` will change if header or payload changes. It's calculated as a
 hash of header field, which contains hash of object's payload.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | Object's unique identifier. Object is content-addressed. It means id will change if header or payload changes. It's calculated as a hash of header field, which contains hash of object's payload |
+| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) |  | Object's unique identifier. |
 | signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Signed object_id |
 | header | [Header](#neo.fs.v2.object.Header) |  | Object metadata headers |
 | payload | [bytes](#bytes) |  | Payload bytes. |
@ -645,11 +675,11 @@ Short header fields
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) |  | Object format version. |
+| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) |  | Object format version. Effectively the version of API library used to create particular object |
 | creation_epoch | [uint64](#uint64) |  | Epoch when the object was created |
 | owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) |  | Object's owner |
 | object_type | [ObjectType](#neo.fs.v2.object.ObjectType) |  | Type of the object payload content |
-| payload_length | [uint64](#uint64) |  | Size of payload in bytes. 0xFFFFFFFFFFFFFFFF means `payload_length` is unknown |
+| payload_length | [uint64](#uint64) |  | Size of payload in bytes. `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown |
 <!-- end messages -->
@ -669,13 +699,13 @@ Type of match expression
 <a name="neo.fs.v2.object.ObjectType"></a>
 ### ObjectType
-Type of the object payload content
+Type of the object payload content.
 | Name | Number | Description |
 | ---- | ------ | ----------- |
 | REGULAR | 0 | Just a normal object |
 | TOMBSTONE | 1 | Used internally to identify deleted objects |
-| STORAGE_GROUP | 2 | Identifies that the object holds StorageGroup information |
+| STORAGE_GROUP | 2 | StorageGroup information |
 <!-- end enums -->
--- a/proto-docs/refs.md
+++ b/proto-docs/refs.md
@ -31,19 +31,20 @@
 <a name="neo.fs.v2.refs.Address"></a>
 ### Message Address
-Address of object (container id + object id)
+Object in NeoFS can be addressed by it's ContainerID and ObjectID. In string
 format there MUST be a '/' delimeter between them.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| container_id | [ContainerID](#neo.fs.v2.refs.ContainerID) |  | container_id carries container identifier. |
+| container_id | [ContainerID](#neo.fs.v2.refs.ContainerID) |  | Container identifier |
-| object_id | [ObjectID](#neo.fs.v2.refs.ObjectID) |  | object_id carries object identifier. |
+| object_id | [ObjectID](#neo.fs.v2.refs.ObjectID) |  | Object identifier |
 <a name="neo.fs.v2.refs.Checksum"></a>
 ### Message Checksum
-Checksum message
+Checksum message.
 | Field | Type | Label | Description |
@ -55,58 +56,65 @@ Checksum message
 <a name="neo.fs.v2.refs.ContainerID"></a>
 ### Message ContainerID
-NeoFS container identifier.
+NeoFS container identifier. Container structures are immutable and
 content-addressed. `ContainerID` is a 32 byte long SHA256 hash of
 stable-marshalled container message.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| value | [bytes](#bytes) |  | value carries the container identifier in a binary format. |
+| value | [bytes](#bytes) |  | Container identifier in a binary format. |
 <a name="neo.fs.v2.refs.ObjectID"></a>
 ### Message ObjectID
-NeoFS object identifier.
+NeoFS Object unique identifier. Objects are immutable and content-addressed.
 It means `ObjectID` will change if `header` or `payload` changes. `ObjectID`
 is calculated as a hash of `header` field, which contains hash of object's
 payload.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| value | [bytes](#bytes) |  | value carries the object identifier in a binary format. |
+| value | [bytes](#bytes) |  | Object identifier in a binary format |
 <a name="neo.fs.v2.refs.OwnerID"></a>
 ### Message OwnerID
-OwnerID group information about the owner of the NeoFS container.
+OwnerID is a derivative of a user's main public key. The transformation
 algorithm is the same as for Neo3 wallet addresses. Neo3 wallet address can
 be directly used as `OwnerID`.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| value | [bytes](#bytes) |  | value carries the identifier of the container owner in a binary format. |
+| value | [bytes](#bytes) |  | Identifier of the container owner in a binary format |
 <a name="neo.fs.v2.refs.Signature"></a>
 ### Message Signature
-Signature of something in NeoFS
+Signature of something in NeoFS.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| key | [bytes](#bytes) |  | Public key used for signing. |
+| key | [bytes](#bytes) |  | Public key used for signing |
 | sign | [bytes](#bytes) |  | Signature |
 <a name="neo.fs.v2.refs.Version"></a>
 ### Message Version
-Represents API version used by node.
+API version used by a node.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| major | [uint32](#uint32) |  | Major API version. |
+| major | [uint32](#uint32) |  | Major API version |
-| minor | [uint32](#uint32) |  | Minor API version. |
+| minor | [uint32](#uint32) |  | Minor API version |
 <!-- end messages -->
@ -114,12 +122,12 @@ Represents API version used by node.
 <a name="neo.fs.v2.refs.ChecksumType"></a>
 ### ChecksumType
-Checksum algorithm type
+Checksum algorithm type.
 | Name | Number | Description |
 | ---- | ------ | ----------- |
 | CHECKSUM_TYPE_UNSPECIFIED | 0 | Unknown. Not used |
-| TZ | 1 | Tillich-Zemor homomorphic hash funciton |
+| TZ | 1 | Tillich-Zemor homomorphic hash function |
 | SHA256 | 2 | SHA-256 |
--- a/proto-docs/session.md
+++ b/proto-docs/session.md
@ -43,7 +43,10 @@
 <a name="neo.fs.v2.session.SessionService"></a>
 ### Service "neo.fs.v2.session.SessionService"
-Create Session record on Node side
+`SessionService` allows to establish a temporary trust relationship between
 two peer nodes and generate a `SessionToken` as the proof of trust to be
 attached in requests for further verification. Please see corresponding
 section of NeoFS Technical Specification for details.
 ```
 rpc Create(CreateRequest) returns (CreateResponse);
@ -52,7 +55,7 @@ rpc Create(CreateRequest) returns (CreateResponse);
 #### Method Create
-Create opens new session between the client and the server.
+Opens a new session between two peers.
 | Name | Input | Output |
 | ---- | ----- | ------ |
@ -63,7 +66,7 @@ Create opens new session between the client and the server.
 <a name="neo.fs.v2.session.CreateRequest"></a>
 ### Message CreateRequest
-CreateRequest carries an information necessary for opening a session.
+Information necessary for opening a session.
 | Field | Type | Label | Description |
@ -76,19 +79,19 @@ CreateRequest carries an information necessary for opening a session.
 <a name="neo.fs.v2.session.CreateRequest.Body"></a>
 ### Message CreateRequest.Body
-Request body
+Session creation request body
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) |  | Carries an identifier of a session initiator. |
+| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) |  | Dession initiating user's or node's key derived `OwnerID`. |
-| expiration | [uint64](#uint64) |  | Expiration Epoch |
+| expiration | [uint64](#uint64) |  | Session expiration `Epoch` |
 <a name="neo.fs.v2.session.CreateResponse"></a>
 ### Message CreateResponse
-CreateResponse carries an information about the opened session.
+Information about the opened session.
 | Field | Type | Label | Description |
@ -101,13 +104,13 @@ CreateResponse carries an information about the opened session.
 <a name="neo.fs.v2.session.CreateResponse.Body"></a>
 ### Message CreateResponse.Body
-Response body
+Session creation response body
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| id | [bytes](#bytes) |  | id carries an identifier of session token. |
+| id | [bytes](#bytes) |  | Identifier of a newly created session |
-| session_key | [bytes](#bytes) |  | session_key carries a session public key. |
+| session_key | [bytes](#bytes) |  | Public key used for session |
 <!-- end messages -->
@ -132,38 +135,39 @@ Context information for Session Tokens related to ObjectService requests
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| verb | [ObjectSessionContext.Verb](#neo.fs.v2.session.ObjectSessionContext.Verb) |  | Verb is a type of request for which the token is issued |
+| verb | [ObjectSessionContext.Verb](#neo.fs.v2.session.ObjectSessionContext.Verb) |  | Type of request for which the token is issued |
 | address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) |  | Related Object address |
 <a name="neo.fs.v2.session.RequestMetaHeader"></a>
 ### Message RequestMetaHeader
-Information about the request
+Meta information attached to the request. When forwarded between peers,
 request meta headers are folded in matryoshka style.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) |  | Client API version. |
+| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) |  | Peer's API version used |
-| epoch | [uint64](#uint64) |  | Client local epoch number. Set to 0 if unknown. |
+| epoch | [uint64](#uint64) |  | Peer's local epoch number. Set to 0 if unknown. |
-| ttl | [uint32](#uint32) |  | Maximum number of nodes in the request route. |
+| ttl | [uint32](#uint32) |  | Maximum number of intermediate nodes in the request route |
-| x_headers | [XHeader](#neo.fs.v2.session.XHeader) | repeated | Request X-Headers. |
+| x_headers | [XHeader](#neo.fs.v2.session.XHeader) | repeated | Request X-Headers |
-| session_token | [SessionToken](#neo.fs.v2.session.SessionToken) |  | Token is a token of the session within which the request is sent |
+| session_token | [SessionToken](#neo.fs.v2.session.SessionToken) |  | Session token within which the request is sent |
-| bearer_token | [neo.fs.v2.acl.BearerToken](#neo.fs.v2.acl.BearerToken) |  | Bearer is a Bearer token of the request |
+| bearer_token | [neo.fs.v2.acl.BearerToken](#neo.fs.v2.acl.BearerToken) |  | `BearerToken` with eACL overrides for the request |
-| origin | [RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) |  | RequestMetaHeader of the origin request. |
+| origin | [RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) |  | `RequestMetaHeader` of the origin request |
 <a name="neo.fs.v2.session.RequestVerificationHeader"></a>
 ### Message RequestVerificationHeader
-Verification info for request signed by all intermediate nodes
+Verification info for request signed by all intermediate nodes.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
 | body_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Request Body signature. Should be generated once by request initiator. |
-| meta_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Request Meta signature is added and signed by any intermediate node |
+| meta_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Request Meta signature is added and signed by each intermediate node |
-| origin_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Sign previous hops |
+| origin_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Signature of previous hops |
 | origin | [RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) |  | Chain of previous hops signatures |
@ -175,11 +179,11 @@ Information about the response
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) |  | Server API version. |
+| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) |  | Peer's API version used |
-| epoch | [uint64](#uint64) |  | Server local epoch number. |
+| epoch | [uint64](#uint64) |  | Peer's local epoch number |
-| ttl | [uint32](#uint32) |  | Maximum number of nodes in the response route. |
+| ttl | [uint32](#uint32) |  | Maximum number of intermediate nodes in the request route |
-| x_headers | [XHeader](#neo.fs.v2.session.XHeader) | repeated | Response X-Headers. |
+| x_headers | [XHeader](#neo.fs.v2.session.XHeader) | repeated | Response X-Headers |
-| origin | [ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) |  | Carries response meta header of the origin response. |
+| origin | [ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) |  | `ResponseMetaHeader` of the origin request |
 <a name="neo.fs.v2.session.ResponseVerificationHeader"></a>
@ -191,36 +195,36 @@ Verification info for response signed by all intermediate nodes
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
 | body_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Response Body signature. Should be generated once by answering node. |
-| meta_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Response Meta signature is added and signed by any intermediate node |
+| meta_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Response Meta signature is added and signed by each intermediate node |
-| origin_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Sign previous hops |
+| origin_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Signature of previous hops |
 | origin | [ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) |  | Chain of previous hops signatures |
 <a name="neo.fs.v2.session.SessionToken"></a>
 ### Message SessionToken
-NeoFS session token.
+NeoFS Session Token.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| body | [SessionToken.Body](#neo.fs.v2.session.SessionToken.Body) |  | Session Token body |
+| body | [SessionToken.Body](#neo.fs.v2.session.SessionToken.Body) |  | Session Token contains the proof of trust between peers to be attached in requests for further verification. Please see corresponding section of NeoFS Technical Specification for details. |
-| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Signature is a signature of session token information |
+| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) |  | Signature of `SessionToken` information |
 <a name="neo.fs.v2.session.SessionToken.Body"></a>
 ### Message SessionToken.Body
-Session token body
+Session Token body
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| id | [bytes](#bytes) |  | ID is a token identifier. valid UUIDv4 represented in bytes |
+| id | [bytes](#bytes) |  | Token identifier is a valid UUIDv4 in binary form |
-| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) |  | OwnerID carries identifier of the session initiator. |
+| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) |  | Identifier of the session initiator |
-| lifetime | [SessionToken.Body.TokenLifetime](#neo.fs.v2.session.SessionToken.Body.TokenLifetime) |  | Lifetime is a lifetime of the session |
+| lifetime | [SessionToken.Body.TokenLifetime](#neo.fs.v2.session.SessionToken.Body.TokenLifetime) |  | Lifetime of the session |
-| session_key | [bytes](#bytes) |  | SessionKey is a public key of session key |
+| session_key | [bytes](#bytes) |  | Public key used in session |
-| object | [ObjectSessionContext](#neo.fs.v2.session.ObjectSessionContext) |  | ObjectService session context. |
+| object | [ObjectSessionContext](#neo.fs.v2.session.ObjectSessionContext) |  | ObjectService session context |
 <a name="neo.fs.v2.session.SessionToken.Body.TokenLifetime"></a>
@ -239,13 +243,13 @@ Lifetime parameters of the token. Filed names taken from rfc7519.
 <a name="neo.fs.v2.session.XHeader"></a>
 ### Message XHeader
-Extended headers for Request/Response
+Extended headers for Request/Response.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| key | [string](#string) |  | Key of the X-Header. |
+| key | [string](#string) |  | Key of the X-Header |
-| value | [string](#string) |  | Value of the X-Header. |
+| value | [string](#string) |  | Value of the X-Header |
 <!-- end messages -->
--- a/proto-docs/storagegroup.md
+++ b/proto-docs/storagegroup.md
@ -25,16 +25,18 @@
 <a name="neo.fs.v2.storagegroup.StorageGroup"></a>
 ### Message StorageGroup
-StorageGroup groups the information about the NeoFS storage group.
+StorageGroup keeps verification information for Data Audit sessions. Objects
-The storage group consists of objects from single container.
+that require payed storage guaranties are gathered in `StorageGroups` with
 additional information used for proof of storage. `StorageGroup` only
 contains objects from the same container.
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| validation_data_size | [uint64](#uint64) |  | validation_data_size carries the total size of the payloads of the storage group members. |
+| validation_data_size | [uint64](#uint64) |  | Total size of the payloads of objects in the storage group |
-| validation_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) |  | validation_hash carries homomorphic hash from the concatenation of the payloads of the storage group members The order of concatenation is the same as the order of the members in the Members field. |
+| validation_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) |  | Homomorphic hash from the concatenation of the payloads of the storage group members. The order of concatenation is the same as the order of the members in the `members` field. |
-| expiration_epoch | [uint64](#uint64) |  | expiration_epoch carries last NeoFS epoch number of the storage group lifetime. |
+| expiration_epoch | [uint64](#uint64) |  | Last NeoFS epoch number of the storage group lifetime |
-| members | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Members carries the list of identifiers of the object storage group members. The list is strictly ordered. |
+| members | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Strictly ordered list of storage group member objects |
 <!-- end messages -->