Improve GraphQL Documentation with Enhanced Instructions and Links (#84)

lang/en/input_type.php

@@ -1,24 +1,28 @@
 <?php
 
 return [
-    'account_rule.description' => 'The fuel tank account rules.',
-    'account_rule.field.whitelistedCallers' => 'The wallet accounts that are allowed to use the fuel tank.',
-    'account_rule.field.requireToken' => 'The wallet account must have a specific token in their wallet to use the fuel tank.',
-    'dispatch_rule.description' => 'The fuel tank dispatch rules.',
-    'dispatch_rule.field.whitelistedCollections' => 'The list of collections that can be used in the fuel tank.',
-    'dispatch_rule.field.maxFuelBurnPerTransaction' => 'The maximum amount of fuel can be used per transaction.',
-    'fuel_budget.description' => 'The rule for fuel budget.',
-    'fuel_budget.field.amount' => 'The amount of fuel.',
-    'fuel_budget.field.resetPeriod' => 'The period when the amount will reset.',
+    'account_rule.description' => 'Defines criteria that accounts must meet to be added as Fuel Tank User Accounts. These rules are validated during the creation of Tank User Accounts, ensuring only eligible accounts are added based on the specified criteria. [Learn more](https://docs.enjin.io/docs/fuel-tank-pallet#account-rules).',
+    'account_rule.field.whitelistedCallers' => 'Defines a list of accounts (as an array of strings) that are allowed to be added as Fuel Tank User Accounts. Only accounts included in this whitelist can be added.',
+    'account_rule.field.requireToken' => 'Specifies that only accounts holding a specific multiToken are eligible to be added as Fuel Tank User Accounts.',
+    'dispatch_rule.description' => 'Specifies rule sets that are validated when dispatching a transaction subsidized by the Fuel Tank. Each rule set can contain multiple individual rules that control access and permissions, ensuring the dispatch call adheres to the defined criteria.\n**Note:**: A fuel tank must have at least one rule set that includes at least one rule for it to be operational.\n[Learn more](https://docs.enjin.io/docs/fuel-tank-pallet#dispatch-rules).',
+    'dispatch_rule.field.maxFuelBurnPerTransaction' => 'Limits the maximum amount of fuel that can be consumed in a single transaction. Dispatches exceeding this limit will fail',
+    'dispatch_rule.field.requireToken' => 'Specifies that only accounts holding a specific multiToken are eligible to dispatch transactions using this rule set.',
+    'dispatch_rule.field.tankFuelBudget' => 'Sets the total fuel allocated to the rule set. Once the tank\'s fuel budget is depleted, all dispatches using this rule set will fail.',
+    'dispatch_rule.field.userFuelBudget' => 'Defines the total amount of fuel allocated to a specific tank user account. Dispatches from the user will fail once their fuel budget is exhausted.',
+    'dispatch_rule.field.whitelistedCallers' => 'Defines a list of accounts (as an array of strings) that are allowed to dispatch transactions. Only accounts included in this whitelist can dispatch using this rule set.',
+    'dispatch_rule.field.whitelistedCollections' => 'Requires the caller to hold any token from the specified collection. Only accounts owning a token from the collection can dispatch using this rule set.',
+    'fuel_budget.description' => 'Specifies the total amount of fuel allocated. Once the allocated fuel is exhausted, dispatches associated with the budget will fail.',
+    'fuel_budget.field.amount' => 'The total fuel allocated for the specified budget.',
+    'fuel_budget.field.resetPeriod' => 'The recurring period, measured in blocks, after which the allocated fuel automatically resets to its full amount. To effectively disable resets, set this value to the maximum (4,294,967,295).',
     'require_token.description' => 'The rule for requiring a specific token.',
     'require_token.field.collectionId' => 'The collection chain ID.',
     'require_token.field.tokenId' => 'The token chain ID.',
-    'fuel_tank_mutation.description' => 'The fuel tank input fields.',
+    'fuel_tank_mutation.description' => 'Specifies the fields of the fuel tank to be modified. These include options for updating the [User Account Management](https://docs.enjin.io/docs/using-fuel-tanks#user-account-management), [Coverage Policy](https://docs.enjin.io/docs/using-fuel-tanks#coverage-policy), and [Account Rules](https://docs.enjin.io/docs/using-fuel-tanks#account-rules).',
     'dispatch.description' => 'The dispatch call.',
     'dispatch.field.query' => "The GraphQL query. It's required to query the 'id' and 'encodedData' from the result.",
     'dispatch.field.variables' => 'The GraphQL query variables.',
-    'permitted_extrinsics.description' => 'The list of permitted extrinsics in this ruleset.',
-    'require_signature.description' => 'The account that is required to sign the transaction.',
+    'permitted_extrinsics.description' => 'Specifies a list of allowed extrinsic functions that can be executed using this rule set. Only these functions are permitted for dispatch.',
+    'require_signature.description' => 'Requires each call to include a signature from the specified account. The account provided in this argument must sign the call for it to be accepted by the fuel tank. This rule is ideal for scenarios where the `requireSignature` is set to the daemon account, and dispatches are broadcasted from [managed wallets](https://docs.enjin.io/docs/using-managed-wallets). It enables a fuel tank to be restricted to managed wallets without explicitly storing each wallet address, saving storage fees and allowing dynamic whitelisting of dispatch accounts. [Learn more](https://docs.enjin.io/docs/fuel-tank-pallet#require-signature).',
     'require_signature.field.signature' => 'The wallet which we will require to sign the transaction.',
     'dispatch_settings.description' => 'The dispatch settings.',
     'dispatch_settings.field.paysRemainingFee' => 'The flag to pay the remaining fee.',

lang/en/mutation.php

@@ -1,29 +1,55 @@
 <?php
 
 return [
-    'create_fuel_tank.description' => 'Creates a fuel tank.',
+    'create_fuel_tank.description' => 'Creates a fuel tank, a pool of Enjin Coins (ENJ) used to cover transaction fees for eligible users. Fuel tanks are customizable and operate based on defined rules to target specific actions or accounts that meet certain criteria. For more details, refer to the [Fuel Tanks documentation](https://docs.enjin.io/docs/using-fuel-tanks).',
     'create_fuel_tank.args.account' => 'The fuel tank will be created from this wallet account.',
-    'destroy_fuel_tank.description' => 'Destroy the fuel tank.',
-    'destroy_fuel_tank.args.tankId' => 'The wallet address of the fuel tank.',
-    'add_account.description' => 'Adds new account to the fuel tank.',
-    'add_account.args.userId' => 'The wallet account to be added to the fuel tank.',
-    'mutate_fuel_tank.description' => 'Apply \'mutation\' to a fuel tank.',
-    'batch_add_account.description' => 'Adds new account to the fuel tank in batch.',
-    'batch_add_account.args.userIds' => 'The wallet accounts that will be added to the fuel tank.',
-    'remove_account.description' => 'Removes an account from the fuel tank.',
-    'remove_account.args.userId' => 'The wallet account that will be removed from the fuel tank.',
-    'batch_remove_account.description' => 'Removes an account from the fuel tank in batch',
-    'batch_remove_account.args.userIds' => 'The wallet accounts that will be removed from the fuel tank.',
-    'schedule_mutate_freeze_state.description' => 'Schedule mutating of \'is_frozen\' state that determines if fuel tank or rule set can be frozen.',
-    'schedule_mutate_freeze_state.args.ruleSetId' => 'The rule set index.',
-    'insert_rule_set.description' => 'Insert a new rule set for the fuel tank.',
-    'remove_rule_set.description' => 'Remove a rule set from the fuel tank.',
-    'remove_account_rule_data.description' => 'Remove account rule from fuel tank.',
-    'remove_account_rule_data.args.userId' => 'The wallet account.',
-    'force_set_consumption.description' => 'Force set the fuel tank consumption.',
-    'force_set_consumption.args.totalConsumed' => 'The total consumption.',
-    'force_set_consumption.args.lastResetBlock' => 'The last reset block.',
-    'dispatch.description' => 'Dispatch a call using the \'tankId\' subject to the rules of \'ruleSetId\'.',
+    'destroy_fuel_tank.description' => <<<MD
+Destroys a fuel tank, returning the storage deposit and any remaining balance to the fuel tank owner.  
+
+**Prerequisites:**  
+- The fuel tank must be frozen before it can be destroyed.  
+- All Tank User Accounts must be removed prior to destruction.  
+
+Failure to meet these conditions will cause the transaction to fail.  
+MD,
+    'fuel_tank.args.ruleSetId' => 'The ID of the rule set within the specified tank.',
+    'fuel_tank.args.tankId' => 'The fuel tank\'s account address.',
+    'add_account.description' => 'Adds an account to the Fuel Tank\'s [User Accounts](https://docs.enjin.io/docs/fuel-tank-pallet#tank-user-account).\nThis mutation can only be used by the tank owner unless the fuel tank is configured to allow accounts to add themselves. For more information, see the [User Account Management documentation](https://docs.enjin.io/docs/using-fuel-tanks#user-account-management).',
+    'add_account.args.userId' => 'The wallet account address to be added to the fuel tank.',
+    'mutate_fuel_tank.description' => 'Modifies an existing fuel tank\'s [User Account Management](https://docs.enjin.io/docs/using-fuel-tanks#user-account-management), [Coverage Policy](https://docs.enjin.io/docs/using-fuel-tanks#coverage-policy), and [Account Rules](https://docs.enjin.io/docs/using-fuel-tanks#account-rules).\nThe fuel tank must be frozen before it can be mutated. Use the `ScheduleMutateFreezeState` mutation to freeze the tank.',
+    'batch_add_account.description' => 'Adds multiple accounts to the Fuel Tank\'s [User Accounts](https://docs.enjin.io/docs/fuel-tank-pallet#tank-user-account) in a single transaction.\nThis mutation can only be used by the tank owner unless the fuel tank is configured to allow accounts to add themselves. For more information, see the [User Account Management documentation](https://docs.enjin.io/docs/using-fuel-tanks#user-account-management).',
+    'batch_add_account.args.userIds' => 'List of wallet account addresses that will be added to the fuel tank.',
+    'remove_account.description' => 'Removes an account from the Fuel Tank\'s [User Accounts](https://docs.enjin.io/docs/fuel-tank-pallet#tank-user-account). Only the tank owner can remove accounts, except when the fuel tank is configured to allow accounts to add themselves; in this case, users can remove their own account.',
+    'remove_account.args.userId' => 'The wallet account address that will be removed from the fuel tank.',
+    'batch_remove_account.description' => 'Removes multiple accounts from the Fuel Tank\'s [User Accounts](https://docs.enjin.io/docs/fuel-tank-pallet#tank-user-account) in a single transaction. Only the tank owner can remove accounts, except when the fuel tank is configured to allow accounts to add themselves; in this case, users can remove their own account.',
+    'batch_remove_account.args.userIds' => 'List of wallet account addresses that will be removed from the fuel tank.',
+    'schedule_mutate_freeze_state.description' => 'Freezes or thaws a fuel tank or a rule set. If `ruleSetId` is provided, the specified rule set is targeted; otherwise, the fuel tank is targeted.',
+    'schedule_mutate_freeze_state.args.isFrozen' => 'Determines the state of the target. Set to `true` to freeze or `false` to thaw the fuel tank or rule set.',
+    'insert_rule_set.description' => <<<MD
+Inserts a new rule set into a fuel tank or replaces an existing one.  
+
+**Important Considerations:**  
+- If replacing a rule set, a rule that stores data on user accounts might cause the operation to fail. [Learn more](https://docs.enjin.io/docs/fuel-tank-pallet#insert_rule_set).  
+- Adding a rule set requires the fuel tank to be frozen; otherwise, the operation will fail.  
+MD,
+    'insert_rule_set.args.requireAccount' => 'Specifies if the caller must have a Tank User Account to dispatch transactions. If `true`, the caller must have an account, or the dispatch will fail. If `false`, the caller can dispatch without an account. [Learn more](https://docs.enjin.io/docs/fuel-tank-pallet#require-account).',
+    'remove_rule_set.description' => <<<MD
+Removes a rule set from a fuel tank.  
+
+**Important Considerations:**  
+- Rule sets storing data on any accounts cannot be removed and will result in an error. Use the `RemoveAccountRuleData` mutation to clear the data first.  
+- Only the fuel tank owner can call this mutation.  
+- The fuel tank must be frozen; otherwise, the mutation will fail.  
+MD,
+    'remove_account_rule_data.description' => 'Removes account rule data from a Fuel Tank User Account, if it exists. This includes dispatch rule data, such as the amount of fuel used for fuel budgets. The fuel tank or the rule set must be frozen to perform this operation. If neither is frozen, the transaction will fail.',
+    'remove_account_rule_data.args.rule' => 'The rule data which will be removed from the tank user account.',
+    'remove_account_rule_data.args.userId' => 'The wallet account address.',
+    'force_set_consumption.description' => 'Forcefully sets the fuel consumption for either the tank\'s rule set budget or a specific user account\'s fuel budget.\nBy default, this mutation sets the fuel consumption of the tank\'s rule set budget. If the `userId` argument is provided, it adjusts the fuel consumption for the specified user account\'s fuel budget.',
+    'force_set_consumption.args.lastResetBlock' => 'The block number to forcefully set as the last reset block for the target budget (user\'s or tank\'s rule set).',
+    'force_set_consumption.args.totalConsumed' => 'The total fuel consumption to be forcefully set for the target budget (user\'s or tank\'s rule set).',
+    'force_set_consumption.args.userId' => '(Optional) Specifies the user account whose fuel budget consumption will be set. If omitted, the rule set budget is targeted.',
+    'dispatch.description' => 'Broadcasts a transaction through the fuel tank, which covers transaction fees and, if configured, provides a storage deposit. All calls are evaluated against the fuel tank\'s rule sets, and failure to meet the rules will result in an error.\nSome fuel tanks require the caller\'s account to be added to the tank\'s [User Accounts](https://docs.enjin.io/docs/fuel-tank-pallet#tank-user-account) to dispatch. To self-add the caller to the tank and dispatch simultaneously in a single transaction, use the `DispatchAndTouch` mutation.\n[Learn more about dispatching calls using a fuel tank](https://docs.enjin.io/docs/using-fuel-tanks#dispatching-a-call-using-a-fuel-tank).',
     'dispatch.args.paysRemainingFee' => 'Pays remaining fee flag.',
-    'dispatch_and_touch.description' => 'Same as \'Dispatch\', but creates an account for \'origin\' if doesn\'t exist.',
+    'dispatch.args.ruleSetId' => 'The ID of the rule set to dispatch with, within the specified tank.',
+    'dispatch_and_touch.description' => 'Broadcasts a transaction through the fuel tank, covering transaction fees and, if configured, providing a storage deposit. If the caller\'s account is not already added to the fuel tank\'s [User Accounts](https://docs.enjin.io/docs/fuel-tank-pallet#tank-user-account), this mutation adds the account before dispatching the transaction.\nTo dispatch without adding the account, use the `Dispatch` mutation instead.\nAll calls are evaluated against the fuel tank\'s rule sets, and failure to meet the rules will result in an error.[Learn more about dispatching calls using a fuel tank](https://docs.enjin.io/docs/using-fuel-tanks#dispatching-a-call-using-a-fuel-tank).',
 ];

lang/en/type.php

@@ -6,14 +6,35 @@
     'fuel_tank.field.owner_wallet' => 'The wallet account that owns the fuel tank.',
     'fuel_tank.field.name' => 'The fuel tank name.',
     'fuel_tank.field.reservesExistentialDeposit' => '(DEPRECATED) The flag for existential deposit.',
-    'fuel_tank.field.reservesAccountCreationDeposit' => 'The flag for account creation deposit.',
+    'fuel_tank.field.reservesAccountCreationDeposit' => <<<MD
+Determines how accounts are added to the Fuel Tank User Accounts and whether the Fuel Tank covers the storage deposit costs. [Learn more](https://docs.enjin.io/docs/using-fuel-tanks#user-account-management).  
+
+Options:  
+1. **Not provided**  
+   Only the Fuel Tank owner can add accounts to the Fuel Tank User Accounts.  
+
+2. **Set to `false`**  
+   Accounts can add themselves to the Fuel Tank User Accounts, but the Fuel Tank does not provide funds for the Tank User Account Storage Deposit.  
+
+3. **Set to `true`**  
+   Accounts can add themselves to the Fuel Tank User Accounts, and the Fuel Tank covers the required funds for the Tank User Account Storage Deposit.  
+MD,
     'fuel_tank.field.providesDeposit' => '(DEPRECATED) The flag for deposit.',
     'fuel_tank.field.isFrozen' => 'The flag for frozen state.',
     'fuel_tank.field.accountCount' => 'The number of accounts.',
     'fuel_tank.field.accounts' => 'The fuel tank accounts.',
     'fuel_tank.field.accountRules' => 'The fuel tank account rules.',
     'fuel_tank.field.dispatchRules' => 'The fuel tank dispatch rules.',
-    'fuel_tank.field.coveragePolicy' => 'The fuel tank coverage policy.',
+    'fuel_tank.field.coveragePolicy' => <<<MD
+Defines the coverage scope for the Fuel Tank. [Learn more](https://docs.enjin.io/docs/using-fuel-tanks#coverage-policy).  
+
+Options:  
+1. **FEES** *(Default)*  
+   The Fuel Tank subsidizes only transaction fees.  
+
+2. **FEES_AND_DEPOSIT**  
+   The Fuel Tank covers both transaction fees and any storage deposit required by the dispatched call.  
+MD,
     'fuel_tank_rule.description' => 'The fuel tank rules.',
     'fuel_tank_rule.field.rule' => 'The fuel tank rule.',
     'fuel_tank_rule.field.value' => 'The rule values.',

src/GraphQL/Mutations/AddAccountMutation.php

@@ -60,7 +60,7 @@ public function args(): array
         return [
             'tankId' => [
                 'type' => GraphQL::type('String!'),
-                'description' => __('enjin-platform-fuel-tanks::mutation.destroy_fuel_tank.args.tankId'),
+                'description' => __('enjin-platform-fuel-tanks::mutation.fuel_tank.args.tankId'),
             ],
             'userId' => [
                 'type' => GraphQL::type('String!'),

src/GraphQL/Mutations/BatchAddAccountMutation.php

@@ -60,7 +60,7 @@ public function args(): array
         return [
             'tankId' => [
                 'type' => GraphQL::type('String!'),
-                'description' => __('enjin-platform-fuel-tanks::mutation.destroy_fuel_tank.args.tankId'),
+                'description' => __('enjin-platform-fuel-tanks::mutation.fuel_tank.args.tankId'),
             ],
             'userIds' => [
                 'type' => GraphQL::type('[String!]!'),

src/GraphQL/Mutations/BatchRemoveAccountMutation.php

@@ -60,7 +60,7 @@ public function args(): array
         return [
             'tankId' => [
                 'type' => GraphQL::type('String!'),
-                'description' => __('enjin-platform-fuel-tanks::mutation.destroy_fuel_tank.args.tankId'),
+                'description' => __('enjin-platform-fuel-tanks::mutation.fuel_tank.args.tankId'),
             ],
             'userIds' => [
                 'type' => GraphQL::type('[String!]!'),

src/GraphQL/Mutations/DestroyFuelTankMutation.php

@@ -59,7 +59,7 @@ public function args(): array
         return [
             'tankId' => [
                 'type' => GraphQL::type('String!'),
-                'description' => __('enjin-platform-fuel-tanks::mutation.destroy_fuel_tank.args.tankId'),
+                'description' => __('enjin-platform-fuel-tanks::mutation.fuel_tank.args.tankId'),
             ],
             ...$this->getSigningAccountField(),
             ...$this->getIdempotencyField(),