Merge pull request #3329 from Dr-Electron/add-solidity-docs-tool

Add solidity docs tool

.github/workflows/upload-docs.yml

@@ -0,0 +1,47 @@
+name: Build and upload API docs
+
+on:
+  release:
+    types: [published]
+
+env:
+  GH_TOKEN: ${{ github.token }}
+
+permissions:
+  actions: 'write'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: tools/evm/docs-generator
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set Up Node.js
+        uses: actions/setup-node@v3
+
+      - name: Get release version
+        id: get_release_version
+        run: |
+          VERSION=$(echo ${{ github.ref }} | sed -e 's/.*v\([0-9]*\.[0-9]*\).*/\1/')
+          echo VERSION=$VERSION >> $GITHUB_OUTPUT
+      
+      - name: Build reference docs
+        run: |
+          yarn && yarn gen-docs:all
+
+      - name: Compress generated docs
+        run: |
+          tar czvf iscmagic.tar.gz docs/iscmagic/*
+          tar czvf iscutils.tar.gz docs/iscutils/*
+
+      - name: Upload docs to AWS S3
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID_IOTA_WIKI }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY_IOTA_WIKI }}
+          AWS_DEFAULT_REGION: "eu-central-1"
+        run: |
+          aws s3 cp iscmagic.tar.gz s3://files.iota.org/iota-wiki/wasp/${{ steps.get_release_version.outputs.VERSION }}/ --acl public-read
+          aws s3 cp iscutils.tar.gz s3://files.iota.org/iota-wiki/wasp/${{ steps.get_release_version.outputs.VERSION }}/ --acl public-read

packages/vm/core/evm/iscmagic/ERC20BaseTokens.sol

@@ -8,33 +8,76 @@ import "./ISCSandbox.sol";
 import "./ISCPrivileged.sol";
 import "./ISCAccounts.sol";
 
-// The ERC20 contract for ISC L2 base tokens.
+/**
+ * @title ERC20BaseTokens
+ * @dev The ERC20 contract directly mapped to the L1 base token.
+ */
 contract ERC20BaseTokens {
     uint256 private constant MAX_UINT64 = type(uint64).max;
 
+    /**
+     * @dev Emitted when the approval of tokens is granted by a token owner to a spender.
+     *
+     * This event indicates that the token owner has approved the spender to transfer a certain amount of tokens on their behalf.
+     *
+     * @param tokenOwner The address of the token owner who granted the approval.
+     * @param spender The address of the spender who is granted the approval.
+     * @param tokens The amount of tokens approved for transfer.
+     */
     event Approval(
         address indexed tokenOwner,
         address indexed spender,
         uint256 tokens
     );
+
+    /**
+     * @dev Emitted when tokens are transferred from one address to another.
+     *
+     * This event indicates that a certain amount of tokens has been transferred from one address to another.
+     *
+     * @param from The address from which the tokens are transferred.
+     * @param to The address to which the tokens are transferred.
+     * @param tokens The amount of tokens transferred.
+     */
     event Transfer(address indexed from, address indexed to, uint256 tokens);
 
+    /**
+     * @dev Returns the name of the base token.
+     * @return The name of the base token.
+     */
     function name() public view returns (string memory) {
         return __iscSandbox.getBaseTokenProperties().name;
     }
 
+    /**
+     * @dev Returns the symbol of the base token.
+     * @return The symbol of the base token.
+     */
     function symbol() public view returns (string memory) {
         return __iscSandbox.getBaseTokenProperties().tickerSymbol;
     }
 
+    /**
+     * @dev Returns the number of decimals used by the base token.
+     * @return The number of decimals used by the base token.
+     */
     function decimals() public view returns (uint8) {
         return __iscSandbox.getBaseTokenProperties().decimals;
     }
 
+    /**
+     * @dev Returns the total supply of the base token.
+     * @return The total supply of the base token.
+     */
     function totalSupply() public view returns (uint256) {
         return __iscSandbox.getBaseTokenProperties().totalSupply;
     }
 
+    /**
+     * @dev Returns the balance of the specified token owner.
+     * @param tokenOwner The address of the token owner.
+     * @return The balance of the token owner.
+     */
     function balanceOf(address tokenOwner) public view returns (uint256) {
         ISCChainID chainID = __iscSandbox.getChainID();
         ISCAgentID memory ownerAgentID = ISCTypes.newEthereumAgentID(
@@ -44,6 +87,12 @@ contract ERC20BaseTokens {
         return __iscAccounts.getL2BalanceBaseTokens(ownerAgentID);
     }
 
+    /**
+     * @dev Transfers tokens from the caller's account to the specified receiver.
+     * @param receiver The address of the receiver.
+     * @param numTokens The number of tokens to transfer.
+     * @return true.
+     */
     function transfer(
         address receiver,
         uint256 numTokens
@@ -56,12 +105,12 @@ contract ERC20BaseTokens {
         return true;
     }
 
-    // Sets `numTokens` as the allowance of `delegate` over the caller’s tokens.
-    //
-    // NOTE: Base tokens are represented internally as an uint64.
-    //       If numTokens > MAX_UINT64, this call will fail.
-    //       Exception: as a special case, numTokens == MAX_UINT256 can be
-    //       specified as an "infinite" approval.
+    /**
+     * @dev Sets the allowance of `delegate` over the caller's tokens.
+     * @param delegate The address of the delegate.
+     * @param numTokens The number of tokens to allow.
+     * @return true.
+     */
     function approve(
         address delegate,
         uint256 numTokens
@@ -71,6 +120,12 @@ contract ERC20BaseTokens {
         return true;
     }
 
+    /**
+     * @dev Returns the allowance of the specified owner for the specified delegate.
+     * @param owner The address of the owner.
+     * @param delegate The address of the delegate.
+     * @return The allowance of the owner for the delegate.
+     */
     function allowance(
         address owner,
         address delegate
@@ -79,6 +134,13 @@ contract ERC20BaseTokens {
         return assets.baseTokens;
     }
 
+    /**
+     * @dev Transfers tokens from the specified owner's account to the specified buyer.
+     * @param owner The address of the owner.
+     * @param buyer The address of the buyer.
+     * @param numTokens The number of tokens to transfer.
+     * @return true.
+     */
     function transferFrom(
         address owner,
         address buyer,

packages/vm/core/evm/iscmagic/ERC20ExternalNativeTokens.sol

@@ -5,13 +5,20 @@ pragma solidity >=0.8.11;
 
 import "./ERC20NativeTokens.sol";
 
-// The ERC20 contract for ISC L2 native tokens (off-chain foundry).
+/**
+ * @title ERC20ExternalNativeTokens
+ * @dev The ERC20 contract for externally registered native tokens (off-chain foundry).
+ */
 contract ERC20ExternalNativeTokens is ERC20NativeTokens {
     NativeTokenID private _nativeTokenID;
 
     // TODO: this value is set at contract creation, and may get outdated
     uint256 private _maximumSupply;
 
+    /**
+     * @dev Returns the native token ID.
+     * @return The native token ID.
+     */
     function nativeTokenID()
         public
         view
@@ -21,6 +28,10 @@ contract ERC20ExternalNativeTokens is ERC20NativeTokens {
         return _nativeTokenID;
     }
 
+    /**
+     * @dev Returns the total supply of the native tokens.
+     * @return The total supply of the native tokens.
+     */
     function totalSupply() public view override returns (uint256) {
         return _maximumSupply;
     }

packages/vm/core/evm/iscmagic/ERC20NativeTokens.sol

@@ -1,4 +1,3 @@
-// Copyright 2020 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
 pragma solidity >=0.8.11;
@@ -8,23 +7,47 @@ import "./ISCSandbox.sol";
 import "./ISCAccounts.sol";
 import "./ISCPrivileged.sol";
 
-// The ERC20 contract for ISC L2 native tokens (on-chain foundry).
+/**
+ * @title ERC20NativeTokens
+ * @dev The ERC20 contract native tokens (on-chain foundry).
+ */
 contract ERC20NativeTokens {
     string private _name;
     string private _tickerSymbol;
     uint8 private _decimals;
 
+    /**
+     * @dev Emitted when the allowance of a spender for an owner is set.
+     * @param tokenOwner The owner of the tokens.
+     * @param spender The address allowed to spend the tokens.
+     * @param tokens The amount of tokens allowed to be spent.
+     */
     event Approval(
         address indexed tokenOwner,
         address indexed spender,
         uint256 tokens
     );
+
+    /**
+     * @dev Emitted when tokens are transferred from one address to another.
+     * @param from The address tokens are transferred from.
+     * @param to The address tokens are transferred to.
+     * @param tokens The amount of tokens transferred.
+     */
     event Transfer(address indexed from, address indexed to, uint256 tokens);
 
+    /**
+     * @dev Returns the foundry serial number of the native token.
+     * @return The foundry serial number.
+     */
     function foundrySerialNumber() internal view returns (uint32) {
         return __iscSandbox.erc20NativeTokensFoundrySerialNumber(address(this));
     }
 
+    /**
+     * @dev Returns the native token ID of the native token.
+     * @return The native token ID.
+     */
     function nativeTokenID()
         public
         view
@@ -34,25 +57,46 @@ contract ERC20NativeTokens {
         return __iscSandbox.getNativeTokenID(foundrySerialNumber());
     }
 
+    /**
+     * @dev Returns the name of the native token.
+     * @return The name of the token.
+     */
     function name() public view returns (string memory) {
         return _name;
     }
 
+    /**
+     * @dev Returns the ticker symbol of the native token.
+     * @return The ticker symbol of the token.
+     */
     function symbol() public view returns (string memory) {
         return _tickerSymbol;
     }
 
+    /**
+     * @dev Returns the number of decimals used for the native token.
+     * @return The number of decimals.
+     */
     function decimals() public view returns (uint8) {
         return _decimals;
     }
 
+    /**
+     * @dev Returns the total supply of the native token.
+     * @return The total supply of the token.
+     */
     function totalSupply() public view virtual returns (uint256) {
         return
             __iscSandbox
                 .getNativeTokenScheme(foundrySerialNumber())
                 .maximumSupply;
     }
 
+    /**
+     * @dev Returns the balance of a token owner.
+     * @param tokenOwner The address of the token owner.
+     * @return The balance of the token owner.
+     */
     function balanceOf(address tokenOwner) public view returns (uint256) {
         ISCChainID chainID = __iscSandbox.getChainID();
         ISCAgentID memory ownerAgentID = ISCTypes.newEthereumAgentID(
@@ -66,6 +110,12 @@ contract ERC20NativeTokens {
             );
     }
 
+    /**
+     * @dev Transfers tokens from the sender's address to the receiver's address.
+     * @param receiver The address to transfer tokens to.
+     * @param numTokens The amount of tokens to transfer.
+     * @return true.
+     */
     function transfer(
         address receiver,
         uint256 numTokens
@@ -79,6 +129,12 @@ contract ERC20NativeTokens {
         return true;
     }
 
+    /**
+     * @dev Sets the allowance of a spender to spend tokens on behalf of the owner.
+     * @param delegate The address allowed to spend the tokens.
+     * @param numTokens The amount of tokens allowed to be spent.
+     * @return true.
+     */
     function approve(
         address delegate,
         uint256 numTokens
@@ -93,6 +149,12 @@ contract ERC20NativeTokens {
         return true;
     }
 
+    /**
+     * @dev Returns the amount of tokens that the spender is allowed to spend on behalf of the owner.
+     * @param owner The address of the token owner.
+     * @param delegate The address of the spender.
+     * @return The amount of tokens the spender is allowed to spend.
+     */
     function allowance(
         address owner,
         address delegate
@@ -106,6 +168,12 @@ contract ERC20NativeTokens {
         return 0;
     }
 
+    /**
+     * @dev Compares two byte arrays for equality.
+     * @param a The first byte array.
+     * @param b The second byte array.
+     * @return A boolean indicating whether the byte arrays are equal or not.
+     */
     function bytesEqual(
         bytes memory a,
         bytes memory b
@@ -117,6 +185,13 @@ contract ERC20NativeTokens {
         return true;
     }
 
+    /**
+     * @dev Transfers tokens from one address to another on behalf of a token owner.
+     * @param owner The address from which tokens are transferred.
+     * @param buyer The address to which tokens are transferred.
+     * @param numTokens The amount of tokens to transfer.
+     * @return A boolean indicating whether the transfer was successful or not.
+     */
     function transferFrom(
         address owner,
         address buyer,