Standarize comments to docgen tool format on the FungibleToken contra…

…ct interface
onflow · Nov 23, 2022 · f07e990 · f07e990
1 parent 13babdd
commit f07e990
Show file tree

Hide file tree

Showing 2 changed files with 25 additions and 36 deletions.
diff --git a/contracts/FungibleToken.cdc b/contracts/FungibleToken.cdc
@@ -40,39 +40,24 @@ the deposit function on another user's Vault to complete the transfer.
 
 */
 
-
-/// FungibleToken
-///
 /// The interface that Fungible Token contracts implement.
 ///
 pub contract interface FungibleToken {
 
     /// The total number of tokens in existence.
     /// It is up to the implementer to ensure that the total supply
     /// stays accurate and up to date
-    ///
     pub var totalSupply: UFix64
 
-    /// TokensInitialized
-    ///
     /// The event that is emitted when the contract is created
-    ///
     pub event TokensInitialized(initialSupply: UFix64)
 
-    /// TokensWithdrawn
-    ///
     /// The event that is emitted when tokens are withdrawn from a Vault
-    ///
     pub event TokensWithdrawn(amount: UFix64, from: Address?)
 
-    /// TokensDeposited
-    ///
     /// The event that is emitted when tokens are deposited into a Vault
-    ///
     pub event TokensDeposited(amount: UFix64, to: Address?)
 
-    /// Provider
-    ///
     /// The interface that enforces the requirements for withdrawing
     /// tokens from the implementing type.
     ///
@@ -82,7 +67,7 @@ pub contract interface FungibleToken {
     ///
     pub resource interface Provider {
 
-        /// withdraw subtracts tokens from the owner's Vault
+        /// Subtracts tokens from the owner's Vault
         /// and returns a Vault with the removed tokens.
         ///
         /// The function's access level is public, but this is not a problem
@@ -97,6 +82,9 @@ pub contract interface FungibleToken {
         /// capability that allows all users to access the provider
         /// resource through a reference.
         ///
+        /// @param amount: The amount of tokens to be withdrawn from the vault
+        /// @return The Vault resource containing the withdrawn funds
+        /// 
         pub fun withdraw(amount: UFix64): @Vault {
             post {
                 // `result` refers to the return value
@@ -106,8 +94,6 @@ pub contract interface FungibleToken {
         }
     }
 
-    /// Receiver
-    ///
     /// The interface that enforces the requirements for depositing
     /// tokens into the implementing type.
     ///
@@ -118,13 +104,13 @@ pub contract interface FungibleToken {
     ///
     pub resource interface Receiver {
 
-        /// deposit takes a Vault and deposits it into the implementing resource type
+        /// Takes a Vault and deposits it into the implementing resource type
+        ///
+        /// @param from: The Vault resource containing the funds that will be deposited
         ///
         pub fun deposit(from: @Vault)
     }
 
-    /// Balance
-    ///
     /// The interface that contains the `balance` field of the Vault
     /// and enforces that when new Vaults are created, the balance
     /// is initialized correctly.
@@ -161,29 +147,28 @@ pub contract interface FungibleToken {
         }
     }
 
-    /// Vault
-    ///
     /// The resource that contains the functions to send and receive tokens.
+    /// The declaration of a concrete type in a contract interface means that
+    /// every Fungible Token contract that implements the FungibleToken interface
+    /// must define a concrete `Vault` resource that conforms to the `Provider`, `Receiver`,
+    /// and `Balance` interfaces, and declares their required fields and functions
     ///
     pub resource Vault: Provider, Receiver, Balance {
 
-        // The declaration of a concrete type in a contract interface means that
-        // every Fungible Token contract that implements the FungibleToken interface
-        // must define a concrete `Vault` resource that conforms to the `Provider`, `Receiver`,
-        // and `Balance` interfaces, and declares their required fields and functions
-
         /// The total balance of the vault
-        ///
         pub var balance: UFix64
 
         // The conforming type must declare an initializer
-        // that allows prioviding the initial balance of the Vault
+        // that allows providing the initial balance of the Vault
         //
         init(balance: UFix64)
 
-        /// withdraw subtracts `amount` from the Vault's balance
+        /// Subtracts `amount` from the Vault's balance
         /// and returns a new Vault with the subtracted balance
         ///
+        /// @param amount: The amount of tokens to be withdrawn from the vault
+        /// @return The Vault resource containing the withdrawn funds
+        ///
         pub fun withdraw(amount: UFix64): @Vault {
             pre {
                 self.balance >= amount:
@@ -198,7 +183,9 @@ pub contract interface FungibleToken {
             }
         }
 
-        /// deposit takes a Vault and adds its balance to the balance of this Vault
+        /// Takes a Vault and deposits it into the implementing resource type
+        ///
+        /// @param from: The Vault resource containing the funds that will be deposited
         ///
         pub fun deposit(from: @Vault) {
             // Assert that the concrete type of the deposited vault is the same
@@ -214,7 +201,9 @@ pub contract interface FungibleToken {
         }
     }
 
-    /// createEmptyVault allows any user to create a new Vault that has a zero balance
+    /// Allows any user to create a new Vault that has a zero balance
+    ///
+    /// @return The new Vault resource
     ///
     pub fun createEmptyVault(): @Vault {
         post {