[#194] Generate docs with recent protocol changes

Signed-off-by: Leonard Lyubich <leonard@nspcc.ru>
nspcc-dev · Feb 22, 2022 · 2743e4b · 2743e4b
1 parent fc79cd1
commit 2743e4b
Show file tree

Hide file tree

Showing 6 changed files with 279 additions and 138 deletions.
diff --git a/container/service.proto b/container/service.proto
@@ -21,8 +21,8 @@ service ContainerService {
   // is added into smart contract storage.
   //
   // Statuses:
-  // - **OK** (0, SECTION_SUCCESS):
-  // request to save the container has been sent to the sidechain;
+  // - **OK** (0, SECTION_SUCCESS): \
+  //   request to save the container has been sent to the sidechain;
   // - Common failures (SECTION_FAILURE_COMMON).
   rpc Put(PutRequest) returns (PutResponse);
 
@@ -32,26 +32,26 @@ service ContainerService {
   // is added into smart contract storage.
   //
   // Statuses:
-  // - **OK** (0, SECTION_SUCCESS):
-  // request to remove the container has been sent to the sidechain;
+  // - **OK** (0, SECTION_SUCCESS): \
+  //   request to remove the container has been sent to the sidechain;
   // - Common failures (SECTION_FAILURE_COMMON).
   rpc Delete(DeleteRequest) returns (DeleteResponse);
 
   // Returns container structure from `Container` smart contract storage.
   //
   // Statuses:
-  // - **OK** (0, SECTION_SUCCESS):
-  // container has been successfully read;
+  // - **OK** (0, SECTION_SUCCESS): \
+  //   container has been successfully read;
   // - Common failures (SECTION_FAILURE_COMMON);
-  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER):
-  // requested container not found.
+  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
+  //   requested container not found.
   rpc Get(GetRequest) returns (GetResponse);
 
   // Returns all owner's containers from 'Container` smart contract' storage.
   //
   // Statuses:
-  // - **OK** (0, SECTION_SUCCESS):
-  // container list has been successfully read;
+  // - **OK** (0, SECTION_SUCCESS): \
+  //   container list has been successfully read;
   // - Common failures (SECTION_FAILURE_COMMON).
   rpc List(ListRequest) returns (ListResponse);
 
@@ -60,27 +60,27 @@ service ContainerService {
   // added into smart contract storage.
   //
   // Statuses:
-  // - **OK** (0, SECTION_SUCCESS):
-  // request to save container eACL has been sent to the sidechain;
+  // - **OK** (0, SECTION_SUCCESS): \
+  //   request to save container eACL has been sent to the sidechain;
   // - Common failures (SECTION_FAILURE_COMMON).
   rpc SetExtendedACL(SetExtendedACLRequest) returns (SetExtendedACLResponse);
 
   // Returns Extended ACL table and signature from `Container` smart contract
   // storage.
   //
   // Statuses:
-  // - **OK** (0, SECTION_SUCCESS):
-  // container eACL has been successfully read;
+  // - **OK** (0, SECTION_SUCCESS): \
+  //   container eACL has been successfully read;
   // - Common failures (SECTION_FAILURE_COMMON);
-  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER):
-  // container not found.
+  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
+  //   container not found.
   rpc GetExtendedACL(GetExtendedACLRequest) returns (GetExtendedACLResponse);
 
   // Announce container used space values for P2P synchronization.
   //
   // Statuses:
-  // - **OK** (0, SECTION_SUCCESS):
-  // estimation of used space has been successfully announced;
+  // - **OK** (0, SECTION_SUCCESS): \
+  //   estimation of used space has been successfully announced;
   // - Common failures (SECTION_FAILURE_COMMON).
   rpc AnnounceUsedSpace(AnnounceUsedSpaceRequest) returns (AnnounceUsedSpaceResponse);
 }

diff --git a/object/service.proto b/object/service.proto
@@ -20,19 +20,19 @@ service ObjectService {
   // keeping receiving order.
   //
   // Statuses:
-  // - **OK** (0, SECTION_SUCCESS):
-  // object has been successfully read;
+  // - **OK** (0, SECTION_SUCCESS): \
+  //   object has been successfully read;
   // - Common failures (SECTION_FAILURE_COMMON);
-  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER):
-  // object container not found;
-  // - **ACCESS_DENIED** (2048, SECTION_OBJECT):
-  // read access to the object is denied;
-  // - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT):
-  // object not found in container;
-  // - **TOKEN_EXPIRED** (4097, SECTION_SESSION):
-  // provided session token has expired;
-  // - **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT):
-  // the requested object has been marked as deleted.
+  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
+  //   object container not found;
+  // - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
+  //   read access to the object is denied;
+  // - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \
+  //   object not found in container;
+  // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
+  //   provided session token has expired;
+  // - **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \
+  //   the requested object has been marked as deleted.
   rpc Get(GetRequest) returns (stream GetResponse);
 
   // Put the object into container. Request uses gRPC stream. First message
@@ -43,77 +43,77 @@ service ObjectService {
   // Chunk messages SHOULD be sent in direct order of fragmentation.
   //
   // Statuses:
-  // - **OK** (0, SECTION_SUCCESS):
-  // object has been successfully saved in the container;
+  // - **OK** (0, SECTION_SUCCESS): \
+  //   object has been successfully saved in the container;
   // - Common failures (SECTION_FAILURE_COMMON);
-  // - **LOCKED** (2050, SECTION_OBJECT):
-  // placement of an object of type TOMBSTONE that includes at least one locked
-  // object is prohibited;
-  // - **LOCK_NON_REGULAR_OBJECT** (2051, SECTION_OBJECT):
-  // placement of an object of type LOCK that includes at least one object of
-  // type other than REGULAR is prohibited;
-  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER):
-  // object storage container not found;
-  // - **ACCESS_DENIED** (2048, SECTION_OBJECT):
-  // write access to the container is denied;
-  // - **TOKEN_NOT_FOUND** (4096, SECTION_SESSION):
-  // (for trusted object preparation) session private key does not exist or has
+  // - **LOCKED** (2050, SECTION_OBJECT): \
+  //   placement of an object of type TOMBSTONE that includes at least one locked
+  //   object is prohibited;
+  // - **LOCK_NON_REGULAR_OBJECT** (2051, SECTION_OBJECT): \
+  //   placement of an object of type LOCK that includes at least one object of
+  //   type other than REGULAR is prohibited;
+  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
+  //   object storage container not found;
+  // - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
+  //   write access to the container is denied;
+  // - **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \
+  //   (for trusted object preparation) session private key does not exist or has
   // been deleted;
-  // - **TOKEN_EXPIRED** (4097, SECTION_SESSION):
-  // provided session token has expired.
+  // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
+  //   provided session token has expired.
   rpc Put(stream PutRequest) returns (PutResponse);
 
   // Delete the object from a container. There is no immediate removal
   // guarantee. Object will be marked for removal and deleted eventually.
   //
   // Statuses:
-  // - **OK** (0, SECTION_SUCCESS):
-  // object has been successfully marked to be removed from the container;
+  // - **OK** (0, SECTION_SUCCESS): \
+  //   object has been successfully marked to be removed from the container;
   // - Common failures (SECTION_FAILURE_COMMON);
-  // - **LOCKED** (2050, SECTION_OBJECT):
-  // deleting a locked object is prohibited;
-  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER):
-  // object container not found;
-  // - **ACCESS_DENIED** (2048, SECTION_OBJECT):
-  // delete access to the object is denied;
-  // - **TOKEN_EXPIRED** (4097, SECTION_SESSION):
-  // provided session token has expired.
+  // - **LOCKED** (2050, SECTION_OBJECT): \
+  //   deleting a locked object is prohibited;
+  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
+  //   object container not found;
+  // - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
+  //   delete access to the object is denied;
+  // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
+  //   provided session token has expired.
   rpc Delete(DeleteRequest) returns (DeleteResponse);
 
   // Returns the object Headers without data payload. By default full header is
   // returned. If `main_only` request field is set, the short header with only
   // the very minimal information would be returned instead.
   //
   // Statuses:
-  // - **OK** (0, SECTION_SUCCESS):
-  // object header has been successfully read;
+  // - **OK** (0, SECTION_SUCCESS): \
+  //   object header has been successfully read;
   // - Common failures (SECTION_FAILURE_COMMON);
-  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER):
-  // object container not found;
-  // - **ACCESS_DENIED** (2048, SECTION_OBJECT):
-  // access to operation HEAD of the object is denied;
-  // - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT):
-  // object not found in container;
-  // - **TOKEN_EXPIRED** (4097, SECTION_SESSION):
-  // provided session token has expired;
-  // - **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT):
-  // the requested object has been marked as deleted.
+  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
+  //   object container not found;
+  // - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
+  //   access to operation HEAD of the object is denied;
+  // - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \
+  //   object not found in container;
+  // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
+  //   provided session token has expired;
+  // - **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \
+  //   the requested object has been marked as deleted.
   rpc Head(HeadRequest) returns (HeadResponse);
 
   // Search objects in container. Search query allows to match by Object
   // Header's filed values. Please see the corresponding NeoFS Technical
   // Specification section for more details.
   //
   // Statuses:
-  // - **OK** (0, SECTION_SUCCESS):
-  // objects have been successfully selected;
+  // - **OK** (0, SECTION_SUCCESS): \
+  //   objects have been successfully selected;
   // - Common failures (SECTION_FAILURE_COMMON);
-  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER):
-  // search container not found;
-  // - **ACCESS_DENIED** (2048, SECTION_OBJECT):
-  // access to operation SEARCH of the object is denied;
-  // - **TOKEN_EXPIRED** (4097, SECTION_SESSION):
-  // provided session token has expired.
+  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
+  //   search container not found;
+  // - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
+  //   access to operation SEARCH of the object is denied;
+  // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
+  //   provided session token has expired.
   rpc Search(SearchRequest) returns (stream SearchResponse);
 
   // Get byte range of data payload. Range is set as an (offset, length) tuple.
@@ -122,19 +122,19 @@ service ObjectService {
   // order.
   //
   // Statuses:
-  // - **OK** (0, SECTION_SUCCESS):
-  // data range of the object payload has been successfully read;
+  // - **OK** (0, SECTION_SUCCESS): \
+  //   data range of the object payload has been successfully read;
   // - Common failures (SECTION_FAILURE_COMMON);
-  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER):
-  // object container not found;
-  // - **ACCESS_DENIED** (2048, SECTION_OBJECT):
-  // access to operation RANGE of the object is denied;
-  // - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT):
-  // object not found in container;
-  // - **TOKEN_EXPIRED** (4097, SECTION_SESSION):
-  // provided session token has expired;
-  // - **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT):
-  // the requested object has been marked as deleted.
+  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
+  //   object container not found;
+  // - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
+  //   access to operation RANGE of the object is denied;
+  // - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \
+  //   object not found in container;
+  // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
+  //   provided session token has expired;
+  // - **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \
+  //   the requested object has been marked as deleted.
   rpc GetRange(GetRangeRequest) returns (stream GetRangeResponse);
 
   // Returns homomorphic or regular hash of object's payload range after
@@ -143,17 +143,17 @@ service ObjectService {
   // request. Note that hash is calculated for XORed data.
   //
   // Statuses:
-  // - **OK** (0, SECTION_SUCCESS):
-  // data range of the object payload has been successfully hashed;
+  // - **OK** (0, SECTION_SUCCESS): \
+  //   data range of the object payload has been successfully hashed;
   // - Common failures (SECTION_FAILURE_COMMON);
-  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER):
-  // object container not found;
-  // - **ACCESS_DENIED** (2048, SECTION_OBJECT):
-  // access to operation RANGEHASH of the object is denied;
-  // - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT):
-  // object not found in container;
-  // - **TOKEN_EXPIRED** (4097, SECTION_SESSION):
-  // provided session token has expired.
+  // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
+  //   object container not found;
+  // - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
+  //   access to operation RANGEHASH of the object is denied;
+  // - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \
+  //   object not found in container;
+  // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
+  //   provided session token has expired.
   rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse);
 }
 

diff --git a/proto-docs/container.md b/proto-docs/container.md
@@ -85,8 +85,8 @@ verified by Inner Ring nodes. After one more block in sidechain, container
 is added into smart contract storage.
 
 Statuses:
-- **OK** (0, SECTION_SUCCESS):
-request to save the container has been sent to the sidechain;
+- **OK** (0, SECTION_SUCCESS): \
+  request to save the container has been sent to the sidechain;
 - Common failures (SECTION_FAILURE_COMMON).
 
 | Name | Input | Output |
@@ -100,8 +100,8 @@ verified by Inner Ring nodes. After one more block in sidechain, container
 is added into smart contract storage.
 
 Statuses:
-- **OK** (0, SECTION_SUCCESS):
-request to remove the container has been sent to the sidechain;
+- **OK** (0, SECTION_SUCCESS): \
+  request to remove the container has been sent to the sidechain;
 - Common failures (SECTION_FAILURE_COMMON).
 
 | Name | Input | Output |
@@ -112,9 +112,11 @@ request to remove the container has been sent to the sidechain;
 Returns container structure from `Container` smart contract storage.
 
 Statuses:
-- **OK** (0, SECTION_SUCCESS):
-container has been successfully read;
-- Common failures (SECTION_FAILURE_COMMON).
+- **OK** (0, SECTION_SUCCESS): \
+  container has been successfully read;
+- Common failures (SECTION_FAILURE_COMMON);
+- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
+  requested container not found.
 
 | Name | Input | Output |
 | ---- | ----- | ------ |
@@ -124,8 +126,8 @@ container has been successfully read;
 Returns all owner's containers from 'Container` smart contract' storage.
 
 Statuses:
-- **OK** (0, SECTION_SUCCESS):
-container list has been successfully read;
+- **OK** (0, SECTION_SUCCESS): \
+  container list has been successfully read;
 - Common failures (SECTION_FAILURE_COMMON).
 
 | Name | Input | Output |
@@ -138,8 +140,8 @@ immediately. After one more block in sidechain, Extended ACL changes are
 added into smart contract storage.
 
 Statuses:
-- **OK** (0, SECTION_SUCCESS):
-request to save container eACL has been sent to the sidechain;
+- **OK** (0, SECTION_SUCCESS): \
+  request to save container eACL has been sent to the sidechain;
 - Common failures (SECTION_FAILURE_COMMON).
 
 | Name | Input | Output |
@@ -151,9 +153,11 @@ Returns Extended ACL table and signature from `Container` smart contract
 storage.
 
 Statuses:
-- **OK** (0, SECTION_SUCCESS):
-container eACL has been successfully read;
-- Common failures (SECTION_FAILURE_COMMON).
+- **OK** (0, SECTION_SUCCESS): \
+  container eACL has been successfully read;
+- Common failures (SECTION_FAILURE_COMMON);
+- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
+  container not found.
 
 | Name | Input | Output |
 | ---- | ----- | ------ |
@@ -163,8 +167,8 @@ container eACL has been successfully read;
 Announce container used space values for P2P synchronization.
 
 Statuses:
-- **OK** (0, SECTION_SUCCESS):
-estimation of used space has been successfully announced;
+- **OK** (0, SECTION_SUCCESS): \
+  estimation of used space has been successfully announced;
 - Common failures (SECTION_FAILURE_COMMON).
 
 | Name | Input | Output |