add comment to value initialize attribute (#1200)

src/Neo.SmartContract.Framework/Attributes/ByteArrayAttribute.cs

@@ -12,6 +12,22 @@
 
 namespace Neo.SmartContract.Framework.Attributes
 {
+    /// <summary>
+    /// Specifies a byte array value for a static field within a smart contract,
+    /// enabling the field to be initialized at compile time.
+    /// </summary>
+    /// <remarks>
+    /// This attribute is used to initialize fields of type byte[] with a hexadecimal string.
+    ///
+    /// <para>Example:</para>
+    /// <code>
+    /// [ByteArray("0123456789ABCDEF")]
+    /// private static readonly byte[] data = default;
+    /// </code>
+    ///
+    /// The value is converted to a byte array at compile time,
+    /// avoiding runtime conversion overhead.
+    /// </remarks>
     [AttributeUsage(AttributeTargets.Field)]
     public class ByteArrayAttribute(string value) : InitialValueAttribute(value, ContractParameterType.ByteArray)
     {

src/Neo.SmartContract.Framework/Attributes/Hash160Attribute.cs

@@ -12,6 +12,28 @@
 
 namespace Neo.SmartContract.Framework.Attributes
 {
+    /// <summary>
+    /// Specifies a Hash160 value for a static field within a smart contract,
+    /// enabling the field to be initialized at compile time.
+    /// </summary>
+    /// <remarks>
+    /// This attribute is used to initialize fields of type UInt160 or byte[]
+    /// with a Hash160 value, which can be either a NEO address or a 20-byte hexadecimal string.
+    ///
+    /// <para>Examples:</para>
+    /// <code>
+    /// // Using a NEO address
+    /// [Hash160("NXV7ZhHiyM1aHXwpVsRZC6BwNFP2jghXAq")]
+    /// private static readonly UInt160 ownerAddress = default;
+    ///
+    /// // Using a 20-byte script hash
+    /// [Hash160("0x0123456789abcdef0123456789abcdef01234567")]
+    /// private static readonly byte[] contractHash = default;
+    /// </code>
+    ///
+    /// The value is converted to the appropriate type at compile time,
+    /// avoiding runtime conversion overhead.
+    /// </remarks>
     [AttributeUsage(AttributeTargets.Field)]
     public class Hash160Attribute(string value) : InitialValueAttribute(value, ContractParameterType.Hash160)
     {

src/Neo.SmartContract.Framework/Attributes/IntegerAttribute.cs

@@ -12,6 +12,23 @@
 
 namespace Neo.SmartContract.Framework.Attributes
 {
+    /// <summary>
+    /// Specifies an integer value for a static field within a smart contract,
+    /// enabling the field to be initialized at compile time.
+    /// </summary>
+    /// <remarks>
+    /// This attribute is used to initialize fields of numeric types (e.g., int, long, BigInteger)
+    /// with a string representation of an integer value.
+    ///
+    /// <para>Example:</para>
+    /// <code>
+    /// [Integer("1000000")]
+    /// private static readonly BigInteger largeNumber = default;
+    /// </code>
+    ///
+    /// The value is converted to the appropriate numeric type at compile time,
+    /// avoiding runtime conversion overhead.
+    /// </remarks>
     [AttributeUsage(AttributeTargets.Field)]
     public class IntegerAttribute(string value) : InitialValueAttribute(value, ContractParameterType.Integer)
     {

src/Neo.SmartContract.Framework/Attributes/PublicKeyAttribute.cs

@@ -12,6 +12,23 @@
 
 namespace Neo.SmartContract.Framework.Attributes
 {
+    /// <summary>
+    /// Specifies a public key value for a static field within a smart contract,
+    /// enabling the field to be initialized at compile time.
+    /// </summary>
+    /// <remarks>
+    /// This attribute is used to initialize fields of type ECPoint or byte[]
+    /// with a public key in hexadecimal format.
+    ///
+    /// <para>Example:</para>
+    /// <code>
+    /// [PublicKey("03b209fd4f53a7170ea4444e0cb0a6bb6a53c2bd016926989cf85f9b0fba17a70c")]
+    /// private static readonly ECPoint publicKey = default;
+    /// </code>
+    ///
+    /// The value is converted to the appropriate type at compile time,
+    /// avoiding runtime conversion overhead.
+    /// </remarks>
     [AttributeUsage(AttributeTargets.Field)]
     public class PublicKeyAttribute(string value) : InitialValueAttribute(value, ContractParameterType.PublicKey)
     {

src/Neo.SmartContract.Framework/Attributes/SafeAttribute.cs

@@ -1,17 +1,52 @@
 // Copyright (C) 2015-2024 The Neo Project.
-// 
-// The Neo.SmartContract.Framework is free software distributed under the MIT 
-// software license, see the accompanying file LICENSE in the main directory 
-// of the project or http://www.opensource.org/licenses/mit-license.php 
+//
+// The Neo.SmartContract.Framework is free software distributed under the MIT
+// software license, see the accompanying file LICENSE in the main directory
+// of the project or http://www.opensource.org/licenses/mit-license.php
 // for more details.
-// 
+//
 // Redistribution and use in source and binary forms with or without
 // modifications are permitted.
 
 using System;
 
 namespace Neo.SmartContract.Framework.Attributes
 {
+    /// <summary>
+    /// Indicates that a method is safe to call during read-only operations.
+    /// </summary>
+    /// <remarks>
+    /// Methods marked with this attribute are considered read-only and do not modify the contract's state.
+    /// They can be called without incurring GAS costs and are typically used for querying data.
+    ///
+    /// It's important to note that any attempt to perform state-changing operations within a method
+    /// marked as [Safe] will result in the execution failing. This is a security measure to ensure
+    /// that methods declared as safe truly remain read-only.
+    ///
+    /// Safe methods are particularly useful for:
+    /// - Retrieving contract data
+    /// - Performing calculations based on existing state
+    /// - Validating inputs without modifying state
+    ///
+    /// Example usage:
+    /// <code>
+    /// [Safe]
+    /// public static string GetName()
+    /// {
+    ///     return "MyContract";
+    /// }
+    /// </code>
+    ///
+    /// Incorrect usage (will fail execution):
+    /// <code>
+    /// [Safe]
+    /// public static void UpdateName(string newName)
+    /// {
+    ///     // This will cause the execution to fail because it attempts to modify state
+    ///     Storage.Put("ContractName", newName);
+    /// }
+    /// </code>
+    /// </remarks>
     [AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
     public class SafeAttribute : Attribute
     {

src/Neo.SmartContract.Framework/Attributes/StringAttribute.cs

@@ -12,6 +12,22 @@
 
 namespace Neo.SmartContract.Framework.Attributes
 {
+    /// <summary>
+    /// Specifies a string value for a static field within a smart contract,
+    /// enabling the field to be initialized at compile time.
+    /// </summary>
+    /// <remarks>
+    /// This attribute is used to initialize fields of type string with a literal string value.
+    ///
+    /// <para>Example:</para>
+    /// <code>
+    /// [String("Hello, NEO!")]
+    /// private static readonly string greeting = default;
+    /// </code>
+    ///
+    /// The value is assigned to the field at compile time,
+    /// avoiding runtime initialization overhead.
+    /// </remarks>
     [AttributeUsage(AttributeTargets.Field)]
     public class StringAttribute(string value) : InitialValueAttribute(value, ContractParameterType.String)
     {