From 62cc321c3eb2a4af8f2f11755efe7b70f6da46eb Mon Sep 17 00:00:00 2001
From: Alex Vanin <alexey@nspcc.ru>
Date: Fri, 31 Jul 2020 17:47:57 +0300
Subject: [PATCH] [#23] Update comments for autogenerated docs

Signed-off-by: Alex Vanin <alexey@nspcc.ru>
---
 container/service.proto | 38 +++++++++++++++++++++++---------------
 container/types.proto   |  5 ++++-
 2 files changed, 27 insertions(+), 16 deletions(-)

diff --git a/container/service.proto b/container/service.proto
index 5d689e5..1ad1a8d 100644
--- a/container/service.proto
+++ b/container/service.proto
@@ -9,27 +9,35 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
 
 option (gogoproto.stable_marshaler_all) = true;
 
-// Container service provides API for manipulating with the container.
+// Service provides API to access container smart-contract in morph chain
+// via NeoFS node.
 service Service {
-    // Put request proposes container to the inner ring nodes. They will
-    // accept new container if user has enough deposit. All containers
-    // are accepted by the consensus, therefore it is asynchronous process.
+    // Put invokes 'Put' method in container smart-contract and returns
+    // response immediately. After new block in morph chain, request is verified
+    // by inner ring nodes. After one more block in morph chain, container
+    // added into smart-contract storage.
     rpc Put(PutRequest) returns (PutResponse);
 
-    // Delete container removes it from the inner ring container storage. It
-    // also asynchronous process done by consensus.
+    // Delete invokes 'Delete' method in container smart-contract and returns
+    // response immediately. After new block in morph chain, request is verified
+    // by inner ring nodes. After one more block in morph chain, container
+    // removed from smart-contract storage.
     rpc Delete(DeleteRequest) returns (DeleteResponse);
 
-    // Get container returns container instance
+    // Get returns container from container smart-contract storage.
     rpc Get(GetRequest) returns (GetResponse);
 
-    // List returns all user's containers
+    // List returns all owner's containers from container smart-contract
+    // storage.
     rpc List(ListRequest) returns (ListResponse);
 
-    // SetExtendedACL changes extended ACL rules of the container
+    // SetExtendedACL invokes 'SetEACL' method in container smart-contract and
+    // returns response immediately. After new block in morph chain,
+    // Extended ACL added into smart-contract storage.
     rpc SetExtendedACL(SetExtendedACLRequest) returns (SetExtendedACLResponse);
 
-    // GetExtendedACL returns extended ACL rules of the container
+    // GetExtendedACL returns Extended ACL table and signature from container
+    // smart-contract storage.
     rpc GetExtendedACL(GetExtendedACLRequest) returns (GetExtendedACLResponse);
 }
 
@@ -44,7 +52,7 @@ message PutRequest {
 }
 
 message PutResponse {
-    // CID (container id) is a SHA256 hash of the container structure
+    // ContainerID of the new container.
     bytes ContainerID = 1;
 }
 
@@ -61,22 +69,22 @@ message DeleteResponse { }
 
 
 message GetRequest {
-    // CID (container id) is a SHA256 hash of the container structure
+    // ContainerID of the container to get.
     bytes ContainerID = 1;
 }
 
 message GetResponse {
-    // Container is a structure that contains placement rules and owner id
+    // Container that has been requested.
     container.Container Container = 1;
 }
 
 message ListRequest {
-    // OwnerID is a wallet address
+    // OwnerID is a 25 byte NEO3.0 wallet address.
     bytes OwnerID = 1;
 }
 
 message ListResponse {
-    // CID (container id) is list of SHA256 hashes of the container structures
+    // ContainerIDs of containers that belong to the owner.
     repeated bytes ContainerIDs = 1;
 }
 
diff --git a/container/types.proto b/container/types.proto
index 98c1404..9eaf2c0 100644
--- a/container/types.proto
+++ b/container/types.proto
@@ -8,7 +8,10 @@ import "github.com/gogo/protobuf/gogoproto/gogo.proto";
 
 option (gogoproto.stable_marshaler_all) = true;
 
-// The Container service definition.
+// Container is a structure that defines object placement behaviour. Objects
+// can be stored only within containers. They define placement rule, attributes
+// and access control information. ID of the container is a 32 byte long
+// SHA256 hash of stable-marshalled container message.
 message Container {
   // OwnerID is a 25 byte NEO3.0 wallet address.
   bytes OwnerID                 = 1;