[#84] Clarify various types encoding formats

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

container/types.proto

@@ -20,7 +20,7 @@ message Container {
   // Identifier of the container owner
   neo.fs.v2.refs.OwnerID owner_id = 2 [json_name = "ownerID"];
 
-  // Nonce is a 16 byte UUID, used to avoid collisions of container id
+  // Nonce is a 16 byte UUIDv4, used to avoid collisions of `ContainerID`s
   bytes nonce = 3 [json_name = "nonce"];
 
   // `BasicACL` contains access control rules for owner, system, others groups

object/service.proto

@@ -323,7 +323,7 @@ message SearchRequest {
     // * $Object:split.parent \
     //   object_id of parent
     // * $Object:split.splitID \
-    //   16 byte UUID used to identify the split object hierarchy parts
+    //   16 byte UUIDv4 used to identify the split object hierarchy parts
     //
     // There are some well-known filter aliases to match objects by certain
     // properties:

object/types.proto

@@ -11,6 +11,12 @@ import "session/types.proto";
 // Type of the object payload content. Only `REGULAR` type objects can be split,
 // hence `TOMBSTONE` and `STORAGEGROUP` payload is limited by maximal object
 // size.
+//
+// String presentation of object type is PascalCased `ObjectType` enumeration
+// item name:
+// * Regular
+// * Tombstone
+// * StorageGroup
 enum ObjectType {
   // Just a normal object
   REGULAR = 0;
@@ -34,7 +40,7 @@ enum MatchType {
 // Short header fields
 message ShortHeader {
   // Object format version. Effectively the version of API library used to
-  // create particular object
+  // create particular object.
   neo.fs.v2.refs.Version version = 1 [json_name = "version"];
 
   // Epoch when the object was created
@@ -67,7 +73,7 @@ message Header {
   uint64 creation_epoch = 4 [json_name = "creationEpoch"];
 
   // Size of payload in bytes.
-  // `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown
+  // `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown.
   uint64 payload_length = 5 [json_name = "payloadLength"];
 
   // Hash of payload bytes
@@ -76,7 +82,7 @@ message Header {
   // Type of the object payload content
   ObjectType object_type = 7 [json_name = "objectType"];
 
-  // Homomorphic hash of the object payload.
+  // Homomorphic hash of the object payload
   neo.fs.v2.refs.Checksum homomorphic_hash = 8 [json_name = "homomorphicHash"];
 
   // Session token, if it was used during Object creation. Need it to verify
@@ -136,9 +142,9 @@ message Header {
     // List of identifiers of the objects generated by splitting current one.
     repeated neo.fs.v2.refs.ObjectID children = 5 [json_name = "children"];
 
-    // 16 byte UUID used to identify the split object hierarchy parts. Must be
+    // 16 byte UUIDv4 used to identify the split object hierarchy parts. Must be
-    // unique inside container. All objects participating in the split must
+    // unique inside container. All objects participating in the split must have
-    // have the same `split_id` value.
+    // the same `split_id` value.
     bytes split_id = 6 [json_name = "splitID"];
 
   }
@@ -159,6 +165,6 @@ message Object {
   // Object metadata headers
   Header header = 3 [json_name = "header"];
 
-  // Payload bytes.
+  // Payload bytes
   bytes payload = 4 [json_name = "payload"];
 }

refs/types.proto

@@ -5,8 +5,10 @@ package neo.fs.v2.refs;
 option go_package = "github.com/nspcc-dev/neofs-api-go/v2/refs/grpc;refs";
 option csharp_namespace = "NeoFS.API.v2.Refs";
 
-// Object in NeoFS can be addressed by it's ContainerID and ObjectID. In string
+// Objects in NeoFS are addressed by their ContainerID and ObjectID.
-// format there MUST be a '/' delimeter between them.
+//
+// String presentation of `Address` is the concatenation of string encoded
+// `ContainerID` and `ObjectID` delimited by '/' character.
 message Address {
   // Container identifier
   ContainerID container_id = 1 [json_name = "containerID"];
@@ -15,31 +17,46 @@ message Address {
 }
 
 // NeoFS Object unique identifier. Objects are immutable and content-addressed.
-// It means `ObjectID` will change if `header` or `payload` changes. `ObjectID`
+// It means `ObjectID` will change if `header` or `payload` changes.
-// is calculated as a hash of `header` field, which contains hash of object's
+//
-// payload.
+// `ObjectID` is a 32 byte long SHA256 hash of object's `header` field, which,
+// in it's turn, contains hash of object's payload.
+//
+// String presentation is base58 encoded string.
 message ObjectID {
   // Object identifier in a binary format
   bytes value = 1 [json_name = "value"];
 }
 
 // NeoFS container identifier. Container structures are immutable and
-// content-addressed. `ContainerID` is a 32 byte long SHA256 hash of
+// content-addressed.
-// stable-marshalled container message.
+//
+// `ContainerID` is a 32 byte long SHA256 hash of stable-marshalled container
+// message.
+//
+// String presentation is base58 encoded string.
 message ContainerID {
   // Container identifier in a binary format.
   bytes value = 1 [json_name = "value"];
 }
 
-// OwnerID is a derivative of a user's main public key. The transformation
+// `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`.
+//
+// `OwnerID` is a 25 bytes sequence starting with Neo version prefix byte
+// followed by 20 bytes of ScrptHash and 4 bytes of checksum.
+//
+// String presentation is Base58 Check Encoded string.
 message OwnerID {
   // Identifier of the container owner in a binary format
   bytes value = 1 [json_name = "value"];
 }
 
 // API version used by a node.
+//
+// String presentation is a Semantic Versioning 2.0.0 compatible version string
+// with 'v' prefix. I.e. `vX.Y`, where `X` - major number, `Y` - minor number.
 message Version {
   // Major API version
   uint32 major = 1 [json_name = "major"];
@@ -69,6 +86,12 @@ enum ChecksumType {
 }
 
 // Checksum message.
+// Depending on checksum algorithm type the string presentation may vary:
+//
+// * TZ \
+//   Hex encoded string without `0x` prefix
+// * SHA256 \
+//   Hex encoded string without `0x` prefix
 message Checksum {
   // Checksum algorithm type
   ChecksumType type = 1 [json_name = "type"];