diff --git a/src/StdChains.sol b/src/StdChains.sol
index 39388b46..b09340c7 100644
--- a/src/StdChains.sol
+++ b/src/StdChains.sol
@@ -65,7 +65,7 @@ abstract contract StdChains {
 
     bool private fallbackToDefaultRpcUrls = true;
 
-    // The RPC URL will be fetched from config or defaultRpcUrls if possible.
+    /// @dev Gets a chain by alias, resolving RPC as setChain > foundry.toml > env var > default.
     function getChain(string memory chainAlias) internal virtual returns (Chain memory chain) {
         require(bytes(chainAlias).length != 0, "StdChains getChain(string): Chain alias cannot be the empty string.");
 
@@ -79,6 +79,7 @@ abstract contract StdChains {
         chain = getChainWithUpdatedRpcUrl(chainAlias, chain);
     }
 
+    /// @dev Gets a chain by ID, resolving its alias before applying the same RPC priority.
     function getChain(uint256 chainId) internal virtual returns (Chain memory chain) {
         require(chainId != 0, "StdChains getChain(uint256): Chain ID cannot be 0.");
         initializeStdChains();
@@ -94,7 +95,7 @@ abstract contract StdChains {
         chain = getChainWithUpdatedRpcUrl(chainAlias, chain);
     }
 
-    // set chain info, with priority to argument's rpcUrl field.
+    /// @dev Sets chain data for an alias; an explicit rpcUrl takes priority in getChain calls.
     function setChain(string memory chainAlias, ChainData memory chain) internal virtual {
         require(
             bytes(chainAlias).length != 0,
@@ -127,7 +128,7 @@ abstract contract StdChains {
         idToAlias[chain.chainId] = chainAlias;
     }
 
-    // set chain info, with priority to argument's rpcUrl field.
+    /// @dev Convenience overload that delegates to setChain(string, ChainData).
     function setChain(string memory chainAlias, Chain memory chain) internal virtual {
         setChain(chainAlias, ChainData({name: chain.name, chainId: chain.chainId, rpcUrl: chain.rpcUrl}));
     }
@@ -146,8 +147,7 @@ abstract contract StdChains {
         return string(copy);
     }
 
-    // lookup rpcUrl, in descending order of priority:
-    // current -> config (foundry.toml) -> environment variable -> default
+    /// @dev Resolves rpcUrl as current value > foundry.toml > env var > default.
     function getChainWithUpdatedRpcUrl(string memory chainAlias, Chain memory chain)
         private
         view
@@ -184,10 +184,12 @@ abstract contract StdChains {
         return chain;
     }
 
+    /// @dev Enables or disables fallback to default RPC URLs when config/env lookups miss.
     function setFallbackToDefaultRpcUrls(bool useDefault) internal {
         fallbackToDefaultRpcUrls = useDefault;
     }
 
+    /// @dev Lazily registers the default chains once.
     function initializeStdChains() private {
         if (stdChainsInitialized) return;
 
@@ -292,7 +294,7 @@ abstract contract StdChains {
         );
     }
 
-    // set chain info, with priority to chainAlias' rpc url in foundry.toml
+    /// @dev Registers a default chain while keeping its RPC URL overridable by config/env vars.
     function setChainWithDefaultRpcUrl(string memory chainAlias, ChainData memory chain) private {
         string memory rpcUrl = chain.rpcUrl;
         defaultRpcUrls[chainAlias] = rpcUrl;