Updated documentation with comment style

Author: mudgen

.vscode/settings.json

@@ -7,7 +7,9 @@
     "solidity.compileUsingRemoteVersion": "v0.8.30",
 
     // Enable GitHub Copilot
-    "github.copilot.enable": true,
+    "github.copilot.enable": {
+        "*": true
+    },
     "github.copilot.inlineSuggest.enable": true,
     "editor.inlineSuggest.enabled": true,
 

website/docs/design/design-for-composition.mdx

@@ -76,8 +76,10 @@ This requires reusing the `ERC20Storage` struct from `ERC20Facet` and defining a
 Here is the full `ERC20Storage` struct from `ERC20Facet`:
 
 ```solidity
-/// @notice Storage struct for ERC20.
-/// @custom:storage-location erc8042:compose.erc20
+/**
+ * @notice Storage struct for ERC20.
+ * @custom:storage-location erc8042:compose.erc20
+ */
 struct ERC20Storage {
     mapping(address owner => uint256 balance) balanceOf;
     uint256 totalSupply; 
@@ -97,12 +99,16 @@ Only unused variables at the **end** of a struct may be safely removed. In this
 Here is the final struct storage code for `ERC20PermitFacet`:
 
 ```solidity
-/// @notice Storage slot identifier for ERC20 (reused to access token data).
+/**
+ * @notice Storage slot identifier for ERC20 (reused to access token data).
+ */
 bytes32 constant ERC20_STORAGE_POSITION = keccak256("compose.erc20");
 
-/// @notice Storage struct for ERC20 but with `symbol` removed.
-/// @dev Reused struct definition with unused variables at the end removed
-/// @custom:storage-location erc8042:compose.erc20
+/**
+ * @notice Storage struct for ERC20 but with `symbol` removed.
+ * @dev Reused struct definition with unused variables at the end removed
+ * @custom:storage-location erc8042:compose.erc20
+ */
 struct ERC20Storage {
     mapping(address owner => uint256 balance) balanceOf;
     uint256 totalSupply; 
@@ -111,26 +117,34 @@ struct ERC20Storage {
     string name; 
 }
 
-/// @notice Returns the storage for ERC20.
-/// @return s The ERC20 storage struct.
+/**
+ * @notice Returns the storage for ERC20.
+ * @return s The ERC20 storage struct.
+ */
 function getERC20Storage() internal pure returns (ERC20Storage storage s) {
     bytes32 position = ERC20_STORAGE_POSITION;
     assembly {
         s.slot := position
     }
 }
 
-/// @notice Storage slot identifier for Permit functionality.
+/**
+ * @notice Storage slot identifier for Permit functionality.
+ */
 bytes32 constant STORAGE_POSITION = keccak256("compose.erc20.permit");
 
-/// @notice Storage struct for ERC20Permit.
-/// @custom:storage-location erc8042:compose.erc20.permit
+/**
+ * @notice Storage struct for ERC20Permit.
+ * @custom:storage-location erc8042:compose.erc20.permit
+ */
 struct ERC20PermitStorage {
     mapping(address owner => uint256) nonces;
 }
 
-/// @notice Returns the storage for ERC20Permit.
-/// @return s The ERC20Permit storage struct.
+/**
+ * @notice Returns the storage for ERC20Permit.
+ * @return s The ERC20Permit storage struct.
+ */
 function getStorage() internal pure returns (ERC20PermitStorage storage s) {
     bytes32 position = STORAGE_POSITION;
     assembly {
@@ -155,137 +169,181 @@ function getStorage() internal pure returns (ERC20PermitStorage storage s) {
 Here's a complete example showing how to correctly extend `ERC20Facet` by creating a new `ERC20StakingFacet` that adds staking functionality:
 
 ```solidity
-// SPDX-License-Identifier: MIT
+/**
+ * SPDX-License-Identifier: MIT
+ */
 pragma solidity >=0.8.30;
 
 contract ERC20StakingFacet {
-    /// @notice Standard ERC20 Transfer event.
+    /**
+     * @notice Standard ERC20 Transfer event.
+     */
     event Transfer(address indexed _from, address indexed _to, uint256 _value);
 
-    /// @notice Event emitted when tokens are staked.
-    /// @param _account The account staking tokens.
-    /// @param _amount The amount of tokens staked.
+    /**
+     * @notice Event emitted when tokens are staked.
+     * @param _account The account staking tokens.
+     * @param _amount The amount of tokens staked.
+     */
     event TokensStaked(address indexed _account, uint256 _amount);
 
-    /// @notice Event emitted when tokens are unstaked.
-    /// @param _account The account unstaking tokens.
-    /// @param _amount The amount of tokens unstaked.
+    /**
+     * @notice Event emitted when tokens are unstaked.
+     * @param _account The account unstaking tokens.
+     * @param _amount The amount of tokens unstaked.
+     */
     event TokensUnstaked(address indexed _account, uint256 _amount);
 
-    /// @notice Thrown when an account has insufficient balance for a stake operation.
-    /// @param _sender Address attempting to stake.
-    /// @param _balance Current balance of the sender.
-    /// @param _needed Amount required to complete the operation.
+    /**
+     * @notice Thrown when an account has insufficient balance for a stake operation.
+     * @param _sender Address attempting to stake.
+     * @param _balance Current balance of the sender.
+     * @param _needed Amount required to complete the operation.
+     */
     error ERC20InsufficientBalance(address _sender, uint256 _balance, uint256 _needed);
 
-    /// @notice Thrown when attempting to unstake more tokens than are staked.
-    /// @param _account The account attempting to unstake.
-    /// @param _requested The amount requested to unstake.
-    /// @param _staked The amount currently staked.
+    /**
+     * @notice Thrown when attempting to unstake more tokens than are staked.
+     * @param _account The account attempting to unstake.
+     * @param _requested The amount requested to unstake.
+     * @param _staked The amount currently staked.
+     */
     error InsufficientStakedBalance(address _account, uint256 _requested, uint256 _staked);
 
-    /// @notice Storage slot identifier for ERC20 (reused to access token data).
+    /**
+     * @notice Storage slot identifier for ERC20 (reused to access token data).
+     */
     bytes32 constant ERC20_STORAGE_POSITION = keccak256("compose.erc20");
     
-    /// @notice Storage struct for ERC20
-    /// @dev This struct is from ERC20Facet.
-    ///      `balanceOf` is the only variable used in this struct.
-    ///      All variables after it are removed.
-    /// @custom:storage-location erc8042:compose.erc20
+    /**
+     * @notice Storage struct for ERC20
+     * @dev This struct is from ERC20Facet.
+     *      `balanceOf` is the only variable used in this struct.
+     *      All variables after it are removed.
+     * @custom:storage-location erc8042:compose.erc20
+     */
     struct ERC20Storage {
         mapping(address owner => uint256 balance) balanceOf;        
     }    
 
-    /// @notice Returns the storage for ERC20.
-    /// @return s The ERC20 storage struct.
+    /**
+     * @notice Returns the storage for ERC20.
+     * @return s The ERC20 storage struct.
+     */
     function getERC20Storage() internal pure returns (ERC20Storage storage s) {
         bytes32 position = ERC20_STORAGE_POSITION;
         assembly {
             s.slot := position
         }
     }
 
-    /// @notice Storage slot identifier for Staking functionality.
+    /**
+     * @notice Storage slot identifier for Staking functionality.
+     */
     bytes32 constant STAKING_STORAGE_POSITION = keccak256("compose.erc20.staking");
 
-    /// @notice Storage struct for ERC20Staking.
-    /// @custom:storage-location erc8042:compose.erc20.staking
+    /**
+     * @notice Storage struct for ERC20Staking.
+     * @custom:storage-location erc8042:compose.erc20.staking
+     */
     struct ERC20StakingStorage {
         mapping(address account => uint256 stakedBalance) stakedBalances;
         mapping(address account => uint256 stakingStartTime) stakingStartTimes;
     }
 
-    /// @notice Returns the storage for ERC20Staking.
-    /// @return s The ERC20Staking storage struct.
+    /**
+     * @notice Returns the storage for ERC20Staking.
+     * @return s The ERC20Staking storage struct.
+     */
     function getStorage() internal pure returns (ERC20StakingStorage storage s) {
         bytes32 position = STAKING_STORAGE_POSITION;
         assembly {
             s.slot := position
         }
     }
 
-    /// @notice Stakes tokens from the caller's balance.
-    /// @param _amount The amount of tokens to stake.
+    /**
+     * @notice Stakes tokens from the caller's balance.
+     * @param _amount The amount of tokens to stake.
+     */
     function stake(uint256 _amount) external {
         ERC20Storage storage erc20s = getERC20Storage();
         ERC20StakingStorage storage s = getStorage();
 
-        // Check sufficient balance
+        /** 
+         * Check sufficient balance
+         */
         if (erc20s.balanceOf[msg.sender] < _amount) {
             revert ERC20InsufficientBalance(msg.sender, erc20s.balanceOf[msg.sender], _amount);
         }
 
-        // Transfer tokens from user's balance to staked balance
+        /**
+         * Transfer tokens from user's balance to staked balance
+         */
         erc20s.balanceOf[msg.sender] -= _amount;
         erc20s.balanceOf[address(this)] += _amount;
         emit Transfer(msg.sender, address(this), _amount);
 
         s.stakedBalances[msg.sender] += _amount;
 
-        // Record staking start time if this is the first stake
+        /**
+         * Record staking start time if this is the first stake
+         */
         if (s.stakingStartTimes[msg.sender] == 0) {
             s.stakingStartTimes[msg.sender] = block.timestamp;
         }
 
         emit TokensStaked(msg.sender, _amount);
     }
 
-    /// @notice Unstakes tokens and returns them to the caller's balance.
-    /// @param _amount The amount of tokens to unstake.
+    /**
+     * @notice Unstakes tokens and returns them to the caller's balance.
+     * @param _amount The amount of tokens to unstake.
+     */
     function unstake(uint256 _amount) external {
         ERC20Storage storage erc20s = getERC20Storage();
         ERC20StakingStorage storage s = getStorage();
 
-        // Check sufficient staked balance
+        /** 
+         * Check sufficient staked balance 
+         */
         if (s.stakedBalances[msg.sender] < _amount) {
             revert InsufficientStakedBalance(msg.sender, _amount, s.stakedBalances[msg.sender]);
         }
 
-        // Transfer tokens from staked balance back to user's balance
+        /**
+         * Transfer tokens from staked balance back to user's balance
+         */
         s.stakedBalances[msg.sender] -= _amount;
 
         erc20s.balanceOf[address(this)] -= _amount;
         erc20s.balanceOf[msg.sender] += _amount;
         emit Transfer(address(this), msg.sender, _amount);
 
-        // Clear staking start time if all tokens are unstaked
+        /** 
+         * Clear staking start time if all tokens are unstaked 
+         */
         if (s.stakedBalances[msg.sender] == 0) {
             s.stakingStartTimes[msg.sender] = 0;
         }
 
         emit TokensUnstaked(msg.sender, _amount);
     }
 
-    /// @notice Returns the staked balance for an account.
-    /// @param _account The account to check.
-    /// @return The amount of tokens staked by the account.
+    /**
+     * @notice Returns the staked balance for an account.
+     * @param _account The account to check.
+     * @return The amount of tokens staked by the account.
+     */
     function getStakedBalance(address _account) external view returns (uint256) {
         return getStorage().stakedBalances[_account];
     }
 
-    /// @notice Returns the staking start time for an account.
-    /// @param _account The account to check.
-    /// @return The timestamp when the account first staked tokens.
+    /**
+     * @notice Returns the staking start time for an account.
+     * @param _account The account to check.
+     * @return The timestamp when the account first staked tokens.
+     */
     function getStakingStartTime(address _account) external view returns (uint256) {
         return getStorage().stakingStartTimes[_account];
     }

website/docs/foundations/custom-facets.mdx

@@ -15,20 +15,28 @@ Suppose you're building an on-chain game and want to include the `ERC721Facet` i
 You can add your own `GameNFTFacet` that extends functionality while still sharing the same ERC-721 storage through `LibERC721`:
 
 ```Solidity
-// Your custom facet integrates with Compose using libraries
+/**
+ * Your custom facet integrates with Compose using libraries
+ */
 import {LibERC721} from "compose/LibERC721.sol";
 
 contract GameNFTFacet {
     function mintWithGameLogic(address player, uint256 tokenId) external {
-        // Your custom game logic
+        /**
+         * Your custom game logic
+         */
         require(playerHasEnoughPoints(player), "Not enough points");
         
-        // Use LibERC721 to mint - this modifies the SAME storage
-        // that ERC721Facet uses for balanceOf(), ownerOf(), etc.
+        /**
+         * Use LibERC721 to mint - this modifies the SAME storage
+         * that ERC721Facet uses for balanceOf(), ownerOf(), etc.
+         */
         LibERC721.mint(player, tokenId);
         
-        // Now the player owns this NFT and can use standard
-        // ERC721Facet.transferFrom() to transfer it!
+        /**
+         * Now the player owns this NFT and can use standard
+         * ERC721Facet.transferFrom() to transfer it!
+         */
         updatePlayerStats(player);
     }
 }