Added GraphQL type descriptions (planetarium#2074)

* Shorten Descriptions (Under 100 char) * Disable lint rule SA1118 for long description. * Update Libplanet.Explorer/GraphTypes/ActionType.cs Co-authored-by: Swen Mun <longfinfunnel@gmail.com> * Fixed Graph Types accordingly. * Added justification. Co-authored-by: Say Cheong <greymistcube@gmail.com> Co-authored-by: Swen Mun <longfinfunnel@gmail.com>
zeta6 · Jun 16, 2022 · 6b2ccce · 6b2ccce
1 parent 3f29c38
commit 6b2ccce
Show file tree

Hide file tree

Showing 3 changed files with 100 additions and 37 deletions.
diff --git a/Libplanet.Explorer/GraphTypes/ActionType.cs b/Libplanet.Explorer/GraphTypes/ActionType.cs
@@ -17,6 +17,7 @@ public ActionType()
         {
             Field<NonNullGraphType<StringGraphType>>(
                 name: "Raw",
+                description: "Raw Action data ('hex' or 'base64' encoding available.)",
                 arguments: new QueryArguments(
                     new QueryArgument<StringGraphType>
                     {
@@ -48,6 +49,7 @@ public ActionType()
 
             Field<NonNullGraphType<StringGraphType>>(
                 name: "Inspection",
+                description: "A readable representation for debugging.",
                 resolve: ctx => ctx.Source.PlainValue.Inspect(loadAll: true)
             );
 

diff --git a/Libplanet.Explorer/GraphTypes/BlockType.cs b/Libplanet.Explorer/GraphTypes/BlockType.cs
@@ -13,45 +13,79 @@ public class BlockType<T> : ObjectGraphType<Block<T>>
     {
         public BlockType()
         {
+            #pragma warning disable SA1118
+            // We need multiple row of description for clearer, not confusing explanation of field.
             Field<NonNullGraphType<IdGraphType>>(
-                "Hash",
-                resolve: ctx => ctx.Source.Hash.ToString());
-            Field(x => x.Index);
-            Field(x => x.Difficulty);
-            Field(x => x.TotalDifficulty);
+            "Hash",
+            description: "A block's hash.",
+            resolve: ctx => ctx.Source.Hash.ToString()
+            );
+            Field<NonNullGraphType<LongGraphType>>(
+            name: "Index",
+            description: "The height of the block.",
+            resolve: x => x.Source.Index
+            );
+            Field<NonNullGraphType<LongGraphType>>(
+            name: "Difficulty",
+            description: "The mining difficulty that the block's Nonce has to satisfy.",
+            resolve: x => x.Source.Difficulty);
+            Field<NonNullGraphType<BigIntGraphType>>(
+            name: "TotalDifficulty",
+            description: @"The total mining difficulty since the genesis including
+            the block's Difficulty.",
+            resolve: x => x.Source.TotalDifficulty);
             Field<NonNullGraphType<ByteStringType>>(
-                "Nonce",
-                resolve: ctx => ctx.Source.Nonce.ToByteArray()
+            name: "Nonce",
+            description: "The proof-of-work nonce which satisfies the required Difficulty.",
+            resolve: ctx => ctx.Source.Nonce.ToByteArray()
+            );
+            Field(
+            type: typeof(NonNullGraphType<AddressType>),
+            name: "Miner",
+            description: "The address of the miner.",
+            resolve: x => x.Source.Miner
+            );
+            Field(
+            type: typeof(PublicKeyType),
+            name: "PublicKey",
+            description: "The public key of the Miner.",
+            resolve: x => x.Source.PublicKey
             );
-            Field(x => x.Miner, type: typeof(NonNullGraphType<AddressType>));
-            Field(x => x.PublicKey, type: typeof(PublicKeyType));
             Field<BlockType<T>>(
-                "PreviousBlock",
-                resolve: ctx =>
+            name: "PreviousBlock",
+            description: @"The previous block, If it's a genesis block
+            (i.e., its Index is 0) this should be null.",
+            resolve: ctx =>
+            {
+                if (!(ctx.Source.PreviousHash is BlockHash h))
                 {
-                    if (!(ctx.Source.PreviousHash is BlockHash h))
-                    {
-                        return null;
-                    }
+                    return null;
+                }
 
-                    // FIXME: (BlockChain<T>) casting does not work
-                    // REF COMMIT HASH: d50c90933c17a70381ad758719144e01bf9c21dc
-                    HashAlgorithmGetter hashAlgorithmGetter = _ => HashAlgorithmType.Of<SHA256>();
-                    var store = (IStore)ctx.UserContext[nameof(IBlockChainContext<T>.Store)];
-                    return store.GetBlock<T>(hashAlgorithmGetter, h);
-                });
+                // FIXME: (BlockChain<T>) casting does not work
+                // REF COMMIT HASH: d50c90933c17a70381ad758719144e01bf9c21dc
+                HashAlgorithmGetter hashAlgorithmGetter = _ => HashAlgorithmType.Of<SHA256>();
+                var store = (IStore)ctx.UserContext[nameof(IBlockChainContext<T>.Store)];
+                return store.GetBlock<T>(hashAlgorithmGetter, h);
+            });
             Field(x => x.Timestamp);
             Field<NonNullGraphType<ByteStringType>>(
-                "StateRootHash",
-                resolve: ctx => ctx.Source.StateRootHash.ToByteArray());
+            name: "StateRootHash",
+            description: @"The Hash of the resulting states after evaluating
+            transactions and a BlockAction. (if exists)",
+            resolve: ctx => ctx.Source.StateRootHash.ToByteArray());
             Field<ByteStringType>(
-                "Signature",
-                resolve: ctx => ctx.Source.Signature?.ToBuilder()?.ToArray());
+            name: "Signature",
+            description: @"The digital signature of the whole block content
+            (except for Hash, which is derived from the signature and other contents)",
+            resolve: ctx => ctx.Source.Signature?.ToBuilder()?.ToArray());
             Field<NonNullGraphType<ListGraphType<NonNullGraphType<TransactionType<T>>>>>(
-                "transactions"
+            name: "transactions",
+            description: "Transactions belonging to the block."
             );
 
             Name = "Block";
+            #pragma warning restore SA1118
         }
     }
 }
diff --git a/Libplanet.Explorer/GraphTypes/TransactionType.cs b/Libplanet.Explorer/GraphTypes/TransactionType.cs
@@ -17,25 +17,52 @@ public class TransactionType<T> : ObjectGraphType<Transaction<T>>
         public TransactionType()
         {
             Field<NonNullGraphType<IdGraphType>>(
-                "Id",
-                resolve: ctx => ctx.Source.Id.ToString());
-            Field(x => x.Nonce);
-            Field(x => x.Signer, type: typeof(NonNullGraphType<AddressType>));
+            name: "Id",
+            description: "A unique identifier derived from this transaction content.",
+            resolve: ctx => ctx.Source.Id.ToString());
+            Field<NonNullGraphType<LongGraphType>>(
+            name: "Nonce",
+            description: "The number of previous transactions committed by the signer of this tx.",
+            resolve: x => x.Source.Nonce
+            );
+            Field(
+            type: typeof(NonNullGraphType<AddressType>),
+            name: "Signer",
+            description: "An address of the account who signed this transaction.",
+            resolve: x => x.Source.Signer
+            );
             Field<NonNullGraphType<ByteStringType>>(
-                "PublicKey",
-                resolve: ctx => ctx.Source.PublicKey.Format(true)
+            name: "PublicKey",
+            description: "A PublicKey of the account who signed this transaction.",
+            resolve: ctx => ctx.Source.PublicKey.Format(true)
+            );
+            Field(
+            type: typeof(NonNullGraphType<ListGraphType<NonNullGraphType<AddressType>>>),
+            name: "UpdatedAddresses",
+            description: "Addresses whose states were affected by Actions.",
+            resolve: x => x.Source.UpdatedAddresses
+            );
+            Field(
+            type: typeof(NonNullGraphType<ByteStringType>),
+            name: "Signature",
+            description: "A digital signature of the content of this transaction.",
+            resolve: x => x.Source.Signature
             );
             Field(
-                x => x.UpdatedAddresses,
-                type: typeof(NonNullGraphType<ListGraphType<NonNullGraphType<AddressType>>>)
+            type: typeof(NonNullGraphType<DateTimeOffsetGraphType>),
+            name: "Timestamp",
+            description: "The time this transaction was created and signed.",
+            resolve: x => x.Source.Timestamp
             );
-            Field(x => x.Signature, type: typeof(NonNullGraphType<ByteStringType>));
-            Field(x => x.Timestamp);
-            Field<NonNullGraphType<ListGraphType<NonNullGraphType<ActionType<T>>>>>("Actions");
+            Field<NonNullGraphType<ListGraphType<NonNullGraphType<ActionType<T>>>>>(
+                name: "Actions",
+                description: "A list of actions in this transaction."
+                );
 
             // The block including the transaction. - Only RichStore supports.
             Field<ListGraphType<NonNullGraphType<BlockType<T>>>>(
                 name: "BlockRef",
+                description: "The block including the transaction.",
                 resolve: ctx =>
                 {
                     // FIXME: use context with DI.