Update session package docs

Signed-off-by: Stanislav Bogatyrev <stanislav@nspcc.ru>

session/service.proto

@@ -8,41 +8,45 @@ option csharp_namespace = "NeoFS.API.v2.Session";
 import "refs/types.proto";
 import "session/types.proto";
 
-// 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.
 service SessionService {
-  // Create opens new session between the client and the server.
+  // Opens a new session between two peers.
   rpc Create (CreateRequest) returns (CreateResponse);
 }
 
-// CreateRequest carries an information necessary for opening a session.
+// Information necessary for opening a session.
 message CreateRequest {
-  // Request body
+  // Session creation request body
   message Body {
-    // Carries an identifier of a session initiator.
+    // Dession initiating user's or node's key derived `OwnerID`.
     neo.fs.v2.refs.OwnerID owner_id = 1;
-    // Expiration Epoch
+    // Session expiration `Epoch`
     uint64 expiration = 2;
   }
   // Body of create session token request message.
   Body body = 1;
 
-  // Carries request meta information. Header data is used only to regulate message
+  // Carries request meta information. Header data is used only to regulate
-  // transport and does not affect request execution.
+  // message transport and does not affect request execution.
   neo.fs.v2.session.RequestMetaHeader meta_header = 2;
 
-  // Carries request verification information. This header is used to authenticate
+  // Carries request verification information. This header is used to
-  // the nodes of the message route and check the correctness of transmission.
+  // authenticate the nodes of the message route and check the correctness of
+  // transmission.
   neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
 }
 
-// CreateResponse carries an information about the opened session.
+// Information about the opened session.
 message CreateResponse {
-  // Response body
+  // Session creation response body
   message Body {
-    // id carries an identifier of session token.
+    // Identifier of a newly created session
     bytes id = 1;
 
-    // session_key carries a session public key.
+    // Public key used for session
     bytes session_key = 2;
   }
 
@@ -54,7 +58,7 @@ message CreateResponse {
   neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
 
   // Carries response verification information. This header is used to
-  // authenticate the nodes of the message route and check the correctness
+  // authenticate the nodes of the message route and check the correctness of
-  // of transmission.
+  // transmission.
   neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
 }

session/types.proto

@@ -36,21 +36,21 @@ message ObjectSessionContext {
     // Refers to object.GetRangeHash RPC call
     RANGEHASH = 7;
   }
-  // Verb is a type of request for which the token is issued
+  // Type of request for which the token is issued
   Verb verb = 1;
 
   // Related Object address
   neo.fs.v2.refs.Address address = 2;
 }
 
-// NeoFS session token.
+// NeoFS Session Token.
 message SessionToken {
-  // Session token body
+  // Session Token body
   message Body {
-    // ID is a token identifier. valid UUIDv4 represented in bytes
+    // Token identifier is a valid UUIDv4 in binary form
     bytes id = 1;
 
-    // OwnerID carries identifier of the session initiator.
+    // Identifier of the session initiator
     neo.fs.v2.refs.OwnerID owner_id = 2;
 
     // Lifetime parameters of the token. Filed names taken from rfc7519.
@@ -64,84 +64,86 @@ message SessionToken {
       // Issued at Epoch
       uint64 iat = 3;
     }
-    // Lifetime is a lifetime of the session
+    // Lifetime of the session
     TokenLifetime lifetime = 3;
 
-    // SessionKey is a public key of session key
+    // Public key used in session
     bytes session_key = 4;
 
-    // Carries context of the session.
+    // Session Context information
     oneof context {
-      // ObjectService session context.
+      // ObjectService session context
       ObjectSessionContext object = 5;
     }
   }
-  // Session Token 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.
   Body body = 1;
 
-  // Signature is a signature of session token information
+  // Signature of `SessionToken` information
   neo.fs.v2.refs.Signature signature = 2;
 }
 
-// Extended headers for Request/Response
+// Extended headers for Request/Response.
 message XHeader {
-  // Key of the X-Header.
+  // Key of the X-Header
   string key = 1;
 
-  // Value of the X-Header.
+  // Value of the X-Header
   string value = 2;
 }
 
-
+// Meta information attached to the request. When forwarded between peers,
-// Information about the request
+// request meta headers are folded in matryoshka style.
 message RequestMetaHeader {
-  // Client API version.
+  // Peer's API version used
   neo.fs.v2.refs.Version version = 1;
 
-  // Client local epoch number. Set to 0 if unknown.
+  // Peer's local epoch number. Set to 0 if unknown.
   uint64 epoch = 2;
 
-  // Maximum number of nodes in the request route.
+  // Maximum number of intermediate nodes in the request route
   uint32 ttl = 3;
 
-  // Request X-Headers.
+  // Request X-Headers
   repeated XHeader x_headers = 4;
 
-  // Token is a token of the session within which the request is sent
+  // Session token within which the request is sent
   SessionToken session_token = 5;
 
-  // Bearer is a Bearer token of the request
+  // `BearerToken` with eACL overrides for the request
   neo.fs.v2.acl.BearerToken bearer_token = 6;
 
-  // RequestMetaHeader of the origin request.
+  // `RequestMetaHeader` of the origin request
   RequestMetaHeader origin = 7;
 }
 
 // Information about the response
 message ResponseMetaHeader {
-  // Server API version.
+  // Peer's API version used
   neo.fs.v2.refs.Version version = 1;
 
-  // Server local epoch number.
+  // Peer's local epoch number
   uint64 epoch = 2;
 
-  // Maximum number of nodes in the response route.
+  // Maximum number of intermediate nodes in the request route
   uint32 ttl = 3;
 
-  // Response X-Headers.
+  // Response X-Headers
   repeated XHeader x_headers = 4;
 
-  // Carries response meta header of the origin response.
+  // `ResponseMetaHeader` of the origin request
   ResponseMetaHeader origin = 5;
 }
 
-// Verification info for request signed by all intermediate nodes
+// Verification info for request signed by all intermediate nodes.
 message RequestVerificationHeader {
   // Request Body signature. Should be generated once by request initiator.
   neo.fs.v2.refs.Signature body_signature = 1;
-  // Request Meta signature is added and signed by any intermediate node
+  // Request Meta signature is added and signed by each intermediate node
   neo.fs.v2.refs.Signature meta_signature = 2;
-  // Sign previous hops
+  // Signature of previous hops
   neo.fs.v2.refs.Signature origin_signature = 3;
 
   // Chain of previous hops signatures
@@ -152,9 +154,9 @@ message RequestVerificationHeader {
 message ResponseVerificationHeader {
   // Response Body signature. Should be generated once by answering node.
   neo.fs.v2.refs.Signature body_signature = 1;
-  // Response Meta signature is added and signed by any intermediate node
+  // Response Meta signature is added and signed by each intermediate node
   neo.fs.v2.refs.Signature meta_signature = 2;
-  // Sign previous hops
+  // Signature of previous hops
   neo.fs.v2.refs.Signature origin_signature = 3;
 
   // Chain of previous hops signatures