Add missing natspec comments on Smart Contracts functions

bridge/contracts/ATokenBurner.sol

@@ -9,7 +9,10 @@ import "contracts/utils/ImmutableAuth.sol";
 contract ATokenBurner is ImmutableAToken, IStakingTokenBurner {
     constructor() ImmutableFactory(msg.sender) ImmutableAToken() IStakingTokenBurner() {}
 
-    function burn(address to, uint256 amount) public onlyFactory {
-        IStakingToken(_aTokenAddress()).externalBurn(to, amount);
+    /// Burns ATokens
+    /// @param from_ The address from where the tokens will be burned
+    /// @param amount_ The amount of ATokens to be burned
+    function burn(address from_, uint256 amount_) public onlyFactory {
+        IStakingToken(_aTokenAddress()).externalBurn(from_, amount_);
     }
 }

bridge/contracts/ATokenMinter.sol

@@ -9,7 +9,10 @@ import "contracts/utils/ImmutableAuth.sol";
 contract ATokenMinter is ImmutableAToken, IStakingTokenMinter {
     constructor() ImmutableFactory(msg.sender) ImmutableAToken() IStakingTokenMinter() {}
 
-    function mint(address to, uint256 amount) public onlyFactory {
-        IStakingToken(_aTokenAddress()).externalMint(to, amount);
+    /// Mints ATokens
+    /// @param to_ The address to where the tokens will be minted
+    /// @param amount_ The amount of ATokens to be minted
+    function mint(address to_, uint256 amount_) public onlyFactory {
+        IStakingToken(_aTokenAddress()).externalMint(to_, amount_);
     }
 }

bridge/contracts/Foundation.sol

@@ -29,6 +29,9 @@ contract Foundation is
     /// fail if the circuit breaker is tripped. The magic_ parameter is intended
     /// to stop some one from successfully interacting with this method without
     /// first reading the source code and hopefully this comment
+    /// @notice deposits aTokens that will be distributed to stakers evenly
+    /// @param magic_ The required control number to allow operation
+    /// @param amount_ The amount of AToken to be deposited
     function depositToken(uint8 magic_, uint256 amount_) public checkMagic(magic_) {
         // collect tokens
         _safeTransferFromERC20(IERC20Transferable(_aTokenAddress()), msg.sender, amount_);
@@ -41,8 +44,13 @@ contract Foundation is
     /// breaker is tripped the magic_ parameter is intended to stop some one from
     /// successfully interacting with this method without first reading the
     /// source code and hopefully this comment
+    /// @notice deposits eths that will be distributed to stakers evenly
+    /// @param magic_ The required control number to allow operation
     function depositEth(uint8 magic_) public payable checkMagic(magic_) {}
 
+    /// Delegates a call to the specified contract with any set of parameters encoded
+    /// @param target_ The address of the contract to be delagated to
+    /// @param cdata_ The encoded parameters of the delegate call encoded
     function delegateCallAny(address target_, bytes memory cdata_) public payable onlyFactory {
         assembly {
             let size := mload(cdata_)

bridge/contracts/Proxy.sol

@@ -35,6 +35,8 @@ contract Proxy {
         _fallback();
     }
 
+    /// Returns the implementation address (target) of the Proxy
+    /// @return the implementation address
     function getImplementationAddress() public view returns (address) {
         assembly {
             mstore(
@@ -48,6 +50,7 @@ contract Proxy {
         }
     }
 
+    /// Delegates calls to proxy implementation
     function _fallback() internal {
         // make local copy of factory since immutables
         // are not accessable in assembly as of yet

bridge/contracts/Snapshots.sol

@@ -32,15 +32,21 @@ contract Snapshots is Initializable, SnapshotsStorage, ISnapshots {
         _snapshotDesperationFactor = desperationFactor_;
     }
 
+    /// @notice Set snapshot desperation delay
+    /// @param desperationDelay_ The desperation delay
     // todo: compute this value using the dynamic system and the alicenet block times.
     function setSnapshotDesperationDelay(uint32 desperationDelay_) public onlyFactory {
         _snapshotDesperationDelay = desperationDelay_;
     }
 
+    /// @notice Set snapshot desperation factor
+    /// @param desperationFactor_ The desperation factor
     function setSnapshotDesperationFactor(uint32 desperationFactor_) public onlyFactory {
         _snapshotDesperationFactor = desperationFactor_;
     }
 
+    /// @notice Set minimum interval between snapshots
+    /// @param minimumIntervalBetweenSnapshots_ The interval in blocks
     function setMinimumIntervalBetweenSnapshots(uint32 minimumIntervalBetweenSnapshots_)
         public
         onlyFactory
@@ -160,38 +166,58 @@ contract Snapshots is Initializable, SnapshotsStorage, ISnapshots {
         return true;
     }
 
+    /// @notice Gets snapshot desperation factor
+    /// @return The snapshot desperation factor
     function getSnapshotDesperationFactor() public view returns (uint256) {
         return _snapshotDesperationFactor;
     }
 
+    /// @notice Gets snapshot desperation delay
+    /// @return The snapshot desperation delay
     function getSnapshotDesperationDelay() public view returns (uint256) {
         return _snapshotDesperationDelay;
     }
 
+    /// @notice Gets minimal interval between snapshots
+    /// @return The minimal interval between snapshots
     function getMinimumIntervalBetweenSnapshots() public view returns (uint256) {
         return _minimumIntervalBetweenSnapshots;
     }
 
+    /// @notice Gets the chain Id
+    /// @return The chain Id
     function getChainId() public view returns (uint256) {
         return _chainId;
     }
 
+    /// @notice Gets the epoch from epoch register
+    /// @return The epoch from epoch register
     function getEpoch() public view returns (uint256) {
         return _epochRegister().get();
     }
 
+    /// @notice Gets the epoch length
+    /// @return The epoch length
     function getEpochLength() public view returns (uint256) {
         return _epochLength;
     }
 
+    /// @notice Gets the chain Id from snapshot for specified epoch
+    /// @param epoch_ The epoch of the snapshot
+    /// @return The chain Id of the snapshot at the epoch specified
     function getChainIdFromSnapshot(uint256 epoch_) public view returns (uint256) {
         return _getSnapshot(uint32(epoch_)).blockClaims.chainId;
     }
 
+    /// @notice Gets the chain Id from latest snapshot
+    /// @return The chain Id of latest snapshot
     function getChainIdFromLatestSnapshot() public view returns (uint256) {
         return _getLatestSnapshot().blockClaims.chainId;
     }
 
+    /// @notice Gets block claims from snapshot for specified epoch
+    /// @param epoch_ The epoch of the snapshot
+    /// @return The block claims from snapshot for specified epoch
     function getBlockClaimsFromSnapshot(uint256 epoch_)
         public
         view
@@ -200,6 +226,8 @@ contract Snapshots is Initializable, SnapshotsStorage, ISnapshots {
         return _getSnapshot(uint32(epoch_)).blockClaims;
     }
 
+    /// @notice Gets block claims from latest snapshot
+    /// @return The block claims from latest snapshot
     function getBlockClaimsFromLatestSnapshot()
         public
         view
@@ -208,30 +236,48 @@ contract Snapshots is Initializable, SnapshotsStorage, ISnapshots {
         return _getLatestSnapshot().blockClaims;
     }
 
+    /// @notice Gets committed height from snapshot at specified epoch
+    /// @param epoch_ The epoch of the snapshot
+    /// @return The committed height from snapshot at specified epoch
     function getCommittedHeightFromSnapshot(uint256 epoch_) public view returns (uint256) {
         return _getSnapshot(uint32(epoch_)).committedAt;
     }
 
+    /// @notice Gets committed height from latest snapshot
+    /// @return The committed height from latest snapshot
     function getCommittedHeightFromLatestSnapshot() public view returns (uint256) {
         return _getLatestSnapshot().committedAt;
     }
 
+    /// @notice Gets alicenet height from snapshot at specified epoch
+    /// @param epoch_ The epoch of the snapshot
+    /// @return Alicenet height from snapshot at specified epoch
     function getAliceNetHeightFromSnapshot(uint256 epoch_) public view returns (uint256) {
         return _getSnapshot(uint32(epoch_)).blockClaims.height;
     }
 
+    /// @notice Gets alicenet height from latest snapshot
+    /// @return Alicenet height from latest snapshot
     function getAliceNetHeightFromLatestSnapshot() public view returns (uint256) {
         return _getLatestSnapshot().blockClaims.height;
     }
 
+    /// @notice Gets snapshot for specified epoch
+    /// @param epoch_ The epoch of the snapshot
+    /// @return The snapshot at specified epoch
     function getSnapshot(uint256 epoch_) public view returns (Snapshot memory) {
         return _getSnapshot(uint32(epoch_));
     }
 
+    /// @notice Gets latest snapshot
+    /// @return The latest snapshot
     function getLatestSnapshot() public view returns (Snapshot memory) {
         return _getLatestSnapshot();
     }
 
+    /// @notice Gets epoch for specified height
+    /// @param height The height specified
+    /// @return The epoch at specified height
     function getEpochFromHeight(uint256 height) public view returns (uint256) {
         return _getEpochFromHeight(uint32(height));
     }
@@ -277,6 +323,10 @@ contract Snapshots is Initializable, SnapshotsStorage, ISnapshots {
         return isValidatorElected;
     }
 
+    /// @notice Checks if validator is the one elected to perform snapshot
+    /// @param validator The validator to be checked
+    /// @param lastSnapshotCommittedAt Block number of last snapshot committed
+    /// @param groupSignatureHash The block groups signature hash
     function _isValidatorElectedToPerformSnapshot(
         address validator,
         uint256 lastSnapshotCommittedAt,
@@ -306,6 +356,10 @@ contract Snapshots is Initializable, SnapshotsStorage, ISnapshots {
         }
     }
 
+    /// @notice Validates Block Claims for an epoch
+    /// @param epoch The epoch to be validated
+    /// @param bClaims_ Encoded block claims
+    /// @return blockClaims as struct if valid
     function _parseAndValidateBClaims(uint32 epoch, bytes calldata bClaims_)
         internal
         view
@@ -322,6 +376,10 @@ contract Snapshots is Initializable, SnapshotsStorage, ISnapshots {
         }
     }
 
+    /// @notice Checks block claims signature
+    /// @param groupSignature_ The group signature
+    /// @param bClaims_ The block claims to be checked
+    /// @return signature validity
     function _checkBClaimsSignature(bytes memory groupSignature_, bytes memory bClaims_)
         internal
         view
@@ -352,6 +410,8 @@ contract Snapshots is Initializable, SnapshotsStorage, ISnapshots {
         return (masterPublicKey, signature);
     }
 
+    /// @notice Checks if snapshot minimum interval has passed
+    /// @param lastSnapshotCommittedAt Block number of the last snapshot committed
     function _checkSnapshotMinimumInterval(uint256 lastSnapshotCommittedAt) internal view {
         uint256 minimumIntervalBetweenSnapshots = _minimumIntervalBetweenSnapshots;
         if (block.number < lastSnapshotCommittedAt + minimumIntervalBetweenSnapshots) {
@@ -362,6 +422,13 @@ contract Snapshots is Initializable, SnapshotsStorage, ISnapshots {
         }
     }
 
+    /// @notice Checks if validator is allowed to take snapshots
+    /// @param  numValidators number of current validators
+    /// @param  myIdx index
+    /// @param  blocksSinceDesperation Number of blocks since desperation
+    /// @param  randomSeed Random seed
+    /// @param  desperationFactor Desperation Factor
+    /// @return true if allowed to do snapshots and start and end snapshot range
     function _mayValidatorSnapshot(
         uint256 numValidators,
         uint256 myIdx,

bridge/contracts/libraries/metadata/StakingDescriptor.sol

@@ -20,6 +20,9 @@ library StakingDescriptor {
         uint256 accumulatorToken;
     }
 
+    /// @notice Constructs a token URI out of token URI parameters
+    /// @param params parameters of the token URI
+    /// @return the token URI
     function constructTokenURI(ConstructTokenURIParams memory params)
         internal
         pure
@@ -60,6 +63,9 @@ library StakingDescriptor {
             );
     }
 
+    /// @notice Escapes double quotes from a string
+    /// @param symbol the string to be processed
+    /// @return The string with escaped quotes
     function escapeQuotes(string memory symbol) internal pure returns (string memory) {
         bytes memory symbolBytes = bytes(symbol);
         uint8 quotesCount = 0;
@@ -82,6 +88,9 @@ library StakingDescriptor {
         return symbol;
     }
 
+    /// @notice Generates a SVG image out of a token URI
+    /// @param params parameters of the token URI
+    /// @return svg A string with SVG data
     function generateSVGImage(ConstructTokenURIParams memory params)
         internal
         pure
@@ -98,6 +107,8 @@ library StakingDescriptor {
         return StakingSVG.generateSVG(svgParams);
     }
 
+    /// @notice Generates the first part of the Staking Descriptor
+    /// @return A string with the first part of the Staking Descriptor
     function generateDescriptionPartOne() private pure returns (string memory) {
         return
             string(
@@ -109,6 +120,14 @@ library StakingDescriptor {
             );
     }
 
+    /// @notice Generates the second part of the Staking Descriptor
+    /// @param  tokenId the token id of this descriptor
+    /// @param  shares number of AToken
+    /// @param  freeAfter block number after which the position may be burned.
+    /// @param  withdrawFreeAfter block number after which the position may be collected or burned
+    /// @param  accumulatorEth the last value of the ethState accumulator this account performed a withdraw at
+    /// @param  accumulatorToken the last value of the tokenState accumulator this account performed a withdraw at
+    /// @return A string with the second part of the Staking Descriptor
     function generateDescriptionPartTwo(
         string memory tokenId,
         string memory shares,