Add: comment doc for Framework.Services (#1460)

Author: Wi1l-B0t

src/Neo.SmartContract.Framework/Services/CallFlags.cs

@@ -16,15 +16,43 @@ namespace Neo.SmartContract.Framework.Services
     [Flags]
     public enum CallFlags : byte
     {
+        /// <summary>
+        /// No flag is set.
+        /// </summary>
         None = 0,
 
+        /// <summary>
+        /// Indicates that the contract can read the states.
+        /// </summary>
         ReadStates = 0b00000001,
+
+        /// <summary>
+        /// Indicates that the contract can write the states.
+        /// </summary>
         WriteStates = 0b00000010,
+
+        /// <summary>
+        /// Indicates that the contract can call other contracts.
+        /// </summary>
         AllowCall = 0b00000100,
+        /// <summary>
+        /// Indicates that the contract can notify other contracts.
+        /// </summary>
         AllowNotify = 0b00001000,
 
+        /// <summary>
+        /// Indicates that the contract can read and write the states.
+        /// </summary>
         States = ReadStates | WriteStates,
+
+        /// <summary>
+        /// Indicates that the contract can read the states and call other contracts.
+        /// </summary>
         ReadOnly = ReadStates | AllowCall,
+
+        /// <summary>
+        /// Indicates that the contract can read and write the states and call other contracts and notify other contracts.
+        /// </summary>
         All = States | AllowCall | AllowNotify
     }
 }

src/Neo.SmartContract.Framework/Services/Contract.cs

@@ -17,39 +17,68 @@ namespace Neo.SmartContract.Framework.Services
     public class Contract
     {
         /// <summary>
-        /// Id
+        /// Id. It generated by the system when the contract is deployed.
         /// </summary>
         public readonly int Id;
 
         /// <summary>
-        /// UpdateCounter
+        /// UpdateCounter. It is used to track the number of updates to the contract.
         /// </summary>
         public readonly ushort UpdateCounter;
 
         /// <summary>
-        /// Hash
+        /// Hash. It is the hash of the contract and generated when the first deployment.
         /// </summary>
         public readonly UInt160 Hash;
 
         /// <summary>
-        /// Nef
+        /// Nef. It is the NEF file(i.e. the compiled contract) of the contract.
         /// </summary>
         public readonly ByteString Nef;
 
         /// <summary>
-        /// Manifest
+        /// Manifest. It is the manifest of the contract.
         /// </summary>
         public readonly ContractManifest Manifest;
 
+        /// <summary>
+        /// Calls the contract with the specified method, callflags and arguments.
+        /// <para>
+        /// The execution will fail if:
+        /// 1. The 'scriptHash', or 'method' is null.
+        /// 2. The 'flags' is not a valid <see cref="CallFlags"/>.
+        /// 3. The contract or method does not exist.
+        /// 4. The contract is blocked.
+        /// 5. The arguments.Length is not equal to the parameter count of the method.
+        /// 6. The method is not safe and the contract method is not allowed to be called by the current context.
+        /// </para>
+        /// </summary>
         [Syscall("System.Contract.Call")]
         public static extern object Call(UInt160 scriptHash, string method, CallFlags flags, params object?[]? args);
 
+        /// <summary>
+        /// Gets the <see cref="CallFlags"/> of the current context.
+        /// </summary>
         [Syscall("System.Contract.GetCallFlags")]
         public static extern CallFlags GetCallFlags();
 
+        /// <summary>
+        /// Gets the corresponding account scripthash for the given public key.
+        /// <para>
+        /// The execution will fail if the pubkey is null.
+        /// </para>
+        /// </summary>
         [Syscall("System.Contract.CreateStandardAccount")]
         public static extern UInt160 CreateStandardAccount(ECPoint pubKey);
 
+        /// <summary>
+        /// Gets the corresponding multisig account scripthash for the given public keys.
+        /// <para>
+        /// The execution will fail if:
+        /// 1. The pubkeys is null.
+        /// 2. The 'm' is less than 1 or greater than 1024 or m greater than pubkeys.Length.
+        /// </para>
+        /// </summary>
         [Syscall("System.Contract.CreateMultisigAccount")]
         public static extern UInt160 CreateMultisigAccount(int m, params ECPoint[] pubKey);
     }

src/Neo.SmartContract.Framework/Services/ContractAbi.cs

@@ -11,6 +11,9 @@
 
 namespace Neo.SmartContract.Framework.Services
 {
+    /// <summary>
+    /// Represents the ABI of a contract. Includes methods and events definitions.
+    /// </summary>
     public struct ContractAbi
     {
         public ContractMethodDescriptor[] Methods;

src/Neo.SmartContract.Framework/Services/ContractEventDescriptor.cs

@@ -11,6 +11,9 @@
 
 namespace Neo.SmartContract.Framework.Services
 {
+    /// <summary>
+    /// Represents an event in the ABI of a contract.
+    /// </summary>
     public struct ContractEventDescriptor
     {
         public string Name;

src/Neo.SmartContract.Framework/Services/ContractGroup.cs

@@ -11,9 +11,23 @@
 
 namespace Neo.SmartContract.Framework.Services
 {
+    /// <summary>
+    /// Represents a set of mutually trusted contracts.
+    /// A contract will trust and allow any contract in the same group to invoke it,
+    /// and the user interface will not give any warnings.
+    /// A group is identified by a public key and must be accompanied by a signature 
+    /// for the contract hash to prove that the contract is indeed included in the group.
+    /// </summary>
     public struct ContractGroup
     {
+        /// <summary>
+        /// The public key of the group.
+        /// </summary>
         public ECPoint PubKey;
+
+        /// <summary>
+        /// The signature of the contract hash which can be verified by the `PubKey`.
+        /// </summary>
         public ByteString Signature;
     }
 }

src/Neo.SmartContract.Framework/Services/ContractManifest.cs

@@ -11,6 +11,12 @@
 
 namespace Neo.SmartContract.Framework.Services
 {
+    /// <summary>
+    /// Represents the manifest of a smart contract.
+    /// When a smart contract is deployed, it must explicitly declare the features and permissions it will use.
+    /// When it is running, it will be limited by its declared list of features and permissions, and cannot make any behavior beyond the scope of the list.
+    /// </summary>
+    /// <remarks>For more details, see NEP-15.</remarks>
     public struct ContractManifest
     {
         public string Name;

src/Neo.SmartContract.Framework/Services/ContractMethodDescriptor.cs

@@ -11,6 +11,10 @@
 
 namespace Neo.SmartContract.Framework.Services
 {
+    /// <summary>
+    /// Represents a method in the ABI of a contract.
+    /// Including name, parameters, return type, the offset in the contract NEF file and  it's safe or not.
+    /// </summary>
     public struct ContractMethodDescriptor
     {
         public string Name;

src/Neo.SmartContract.Framework/Services/ContractParameterDefinition.cs

@@ -11,6 +11,9 @@
 
 namespace Neo.SmartContract.Framework.Services
 {
+    /// <summary>
+    /// Represents a parameter of an event or method in ABI, including name and type.
+    /// </summary>
     public struct ContractParameterDefinition
     {
         public string Name;

src/Neo.SmartContract.Framework/Services/ContractPermission.cs

@@ -11,9 +11,28 @@
 
 namespace Neo.SmartContract.Framework.Services
 {
+    /// <summary>
+    /// Represents a permission of a contract. It describes which contracts may be
+    /// invoked and which methods are called.
+    /// If a contract invokes a contract or method that is not declared in the manifest
+    /// at runtime, the invocation will fail.
+    /// </summary>
     public struct ContractPermission
     {
+        /// <summary>
+        /// Indicates which contract to be invoked.
+        /// It can be a hash of a contract, a public key of a group, or a wildcard *.
+        /// If it specifies a hash of a contract, then the contract will be invoked;
+        /// If it specifies a public key of a group, then any contract in this group
+        /// may be invoked; If it specifies a wildcard *, then any contract may be invoked.
+        /// </summary>
         public ByteString Contract;
+
+        /// <summary>
+        /// Indicates which methods to be called.
+        /// It can also be assigned with a wildcard *. If it is a wildcard *,
+        /// then it means that any method can be called.
+        /// </summary>
         public string[] Methods;
     }
 }

src/Neo.SmartContract.Framework/Services/Crypto.cs

@@ -15,10 +15,27 @@ namespace Neo.SmartContract.Framework.Services
 {
     public static class Crypto
     {
+        /// <summary>
+        /// Checks the signature for the current script container(for example: a transaction).
+        /// True if the signature is valid, otherwise false.
+        /// <para>
+        /// The execution will fail if the format of pubkey is invalid.
+        /// </para>
+        /// </summary>
         [Syscall("System.Crypto.CheckSig")]
         public extern static bool CheckSig(ECPoint pubkey, ByteString signature);
 
+        /// <summary>
+        /// Checks the signatures for the current script container(for example: a transaction).
+        /// True if the signatures are valid, otherwise false.
+        /// <para>
+        /// The execution will fail if:
+        /// 1. the pubkeys or signatures is null orempty;
+        /// 2. If signatures.Length > pubkeys.Length.
+        /// 3. The format of any pubkey is invalid.
+        /// </para>
+        /// </summary>
         [Syscall("System.Crypto.CheckMultisig")]
-        public extern static bool CheckMultisig(ECPoint[] pubkey, ByteString[] signature);
+        public extern static bool CheckMultisig(ECPoint[] pubkeys, ByteString[] signatures);
     }
 }