Update netmap package docs

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

netmap/service.proto

@@ -9,18 +9,25 @@ import "netmap/types.proto";
 import "refs/types.proto";
 import "session/types.proto";
 
-// 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.
 service NetmapService {
-  // 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.
   rpc LocalNodeInfo (LocalNodeInfoRequest) returns (LocalNodeInfoResponse);
 }
 
-// Get NodeInfo from the particular node directly
+// Get NodeInfo structure from the particular node directly
 message LocalNodeInfoRequest {
-  //Request body
+  // LocalNodeInfo request body is empty.
   message Body {
   }
-  // Body of the balance request message.
+  // Body of the LocalNodeInfo request message
   Body body = 1;
 
   // Carries request meta information. Header data is used only to regulate
@@ -28,19 +35,19 @@ message LocalNodeInfoRequest {
   neo.fs.v2.session.RequestMetaHeader meta_header = 2;
 
   // Carries request 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.RequestVerificationHeader verify_header = 3;
 }
 
-// Local nod Info, including API Version in use
+// Local Node Info, including API Version in use
 message LocalNodeInfoResponse {
-  //Response body
+  // Local Node Info, including API Version in use.
   message Body {
-    // API version in use
+    // Latest NeoFS API version in use
     neo.fs.v2.refs.Version version = 1;
 
-    // NodeInfo from node itself
+    // NodeInfo structure with recent information from node itself
     NodeInfo node_info = 2;
   }
   // Body of the balance response message.
@@ -51,7 +58,7 @@ message LocalNodeInfoResponse {
   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;
 }

netmap/types.proto

@@ -35,9 +35,9 @@ enum Operation {
   AND = 8;
 }
 
-// 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.
 enum Clause{
   // No modifier defined. Will select nodes from bucket randomly.
   CLAUSE_UNSPECIFIED = 0;
@@ -49,12 +49,13 @@ enum Clause{
   DISTINCT = 2;
 }
 
-// Filter
+// Filter will return the subset of nodes from `NetworkMap` or another filter's
+// results, that will satisfy filter's conditions.
 message Filter {
-  // Name of the filter or a reference to the named filter.
+  // Name of the filter or a reference to the named filter. '*' means
-  // '*' means application to the whole unfiltered NetworkMap
+  // application to the whole unfiltered NetworkMap. At top level it's used as a
-  // At top level it's used as a filter name. At lower levels it's considered to
+  // filter name. At lower levels it's considered to be a reference to another
-  // be a reference to another named filter
+  // named filter
   string name = 1;
 
   // Key to filter
@@ -66,16 +67,18 @@ message Filter {
   // Value to match
   string value = 4;
 
-  // List of inner filters. Top level operation will be applied to the whole list.
+  // List of inner filters. Top level operation will be applied to the whole
+  // list.
   repeated Filter filters = 5;
 }
 
-// Selector
+// Selector chooses a number of nodes from the bucket taking the nearest nodes
+// to the provided `ContainerID` by hash distance.
 message Selector {
   // Selector name to reference in object placement section
   string name = 1;
 
-  // How many nodes to select from bucket
+  // How many nodes to select from the bucket
   uint32 count = 2;
 
   // Selector modifier showing how to form a bucket
@@ -88,22 +91,27 @@ message Selector {
   string filter = 5;
 }
 
-// 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.
 message Replica {
   // How many object replicas to put
   uint32 count = 1;
 
-  // Named selector bucket to put in
+  // Named selector bucket to put replicas
   string selector = 2;
 }
 
-// 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.
 message PlacementPolicy {
-  // Rules to set number of object replicas and place each one into a particular bucket
+  // Rules to set number of object replicas and place each one into a named
+  // bucket
   repeated Replica replicas = 1;
 
   // Container backup factor controls how deep NeoFS will search for nodes
-  // alternatives to include into container.
+  // alternatives to include into container's nodes subset
   uint32 container_backup_factor = 2;
 
   // Set of Selectors to form the container's nodes subset