add comments to the donation functions.

Author: MagicGordon

ref-exchange/release_notes.md

@@ -2,7 +2,7 @@
 
 ### Version 1.9.7
 ```
-BQRaMGsoRafZXJuSb1X66MuXw9vXvSWb4mHQPeaH9uDq
+CMN4goNWHQjsXevLbqAC9nXKTw1yeJqysEfB647uuyro
 ```
 1. fix identity verification for the whitelisted_postfix related functions.
 2. add donation functions.

ref-exchange/src/degen_swap/mod.rs

@@ -721,7 +721,7 @@ impl DegenSwapPool {
     /// The storage should be refunded to the user.
     pub fn share_unregister(&mut self, account_id: &AccountId) {
         let shares = self.shares.remove(account_id);
-        assert!(shares.expect(ERR13_LP_NOT_REGISTERED) == 0, "{}", ERR19_LP_NOT_EMPTY);
+        assert!(shares.expect(ERR13_LP_NOT_REGISTERED) == 0, "{}", ERR19_NONZERO_LP_SHARES);
     }
 
     /// Transfers shares from predecessor to receiver.

ref-exchange/src/donation.rs

@@ -2,6 +2,15 @@ use crate::*;
 
 #[near_bindgen]
 impl Contract {
+    /// The user donates the shares they hold to the protocol.
+    ///
+    /// # Arguments
+    ///
+    /// * `pool_id` - The pool id where the shares are located.
+    /// * `amount` - The donation amount; if it's None, the entire amount will be donated.
+    /// * `unregister` - If `Some(true)`, Will attempt to unregister the shares and refund the user’s storage fees.
+    ///                  The storage fee will be refunded to the user's internal account first; 
+    ///                  if there is no internal account, a transfer will be initiated. 
     #[payable]
     pub fn donation_share(&mut self, pool_id: u64, amount: Option<U128>, unregister: Option<bool>) {
         assert_one_yocto();
@@ -28,6 +37,13 @@ impl Contract {
         event::Event::DonationShare { account_id: &account_id, pool_id, amount: U128(donation_amount) }.emit();
     }
 
+    /// The user donates the tokens they hold to the owner.
+    ///
+    /// # Arguments
+    ///
+    /// * `token_id` - The id of the donated token.
+    /// * `amount` - The donation amount; if it's None, the entire amount will be donated.
+    /// * `unregister` - If `Some(true)`, Will attempt to unregister the tokens.
     #[payable]
     pub fn donation_token(&mut self, token_id: ValidAccountId, amount: Option<U128>, unregister: Option<bool>) {
         assert_one_yocto();

ref-exchange/src/errors.rs

@@ -9,7 +9,7 @@ pub const ERR15_NO_STORAGE_CAN_WITHDRAW: &str = "E15: no storage can withdraw";
 pub const ERR16_STORAGE_WITHDRAW_TOO_MUCH: &str = "E16: storage withdraw too much";
 pub const ERR17_DEPOSIT_LESS_THAN_MIN_STORAGE: &str = "E17: deposit less than min storage";
 pub const ERR18_TOKENS_NOT_EMPTY: &str = "E18: storage unregister tokens not empty";
-pub const ERR19_LP_NOT_EMPTY: &str = "E19: LP not empty";
+pub const ERR19_NONZERO_LP_SHARES: &str = "E19: Nonzero LP shares";
 
 // Accounts.
 

ref-exchange/src/owner.rs

@@ -300,7 +300,6 @@ impl Contract {
         assert!(amount > 0, "{}", ERR29_ILLEGAL_WITHDRAW_AMOUNT);
         let owner_id = self.owner_id.clone();
         let mut account = self.internal_unwrap_account(&owner_id);
-        // Note: subtraction and deregistration will be reverted if the promise fails.
         account.withdraw(&token_id, amount);
         self.accounts.insert(&owner_id, &account.into());
         self.internal_send_tokens(&owner_id, &token_id, amount, skip_unwrap_near)

ref-exchange/src/rated_swap/mod.rs

@@ -719,7 +719,7 @@ impl RatedSwapPool {
     /// The storage should be refunded to the user.
     pub fn share_unregister(&mut self, account_id: &AccountId) {
         let shares = self.shares.remove(account_id);
-        assert!(shares.expect(ERR13_LP_NOT_REGISTERED) == 0, "{}", ERR19_LP_NOT_EMPTY);
+        assert!(shares.expect(ERR13_LP_NOT_REGISTERED) == 0, "{}", ERR19_NONZERO_LP_SHARES);
     }
 
     /// Transfers shares from predecessor to receiver.

ref-exchange/src/simple_pool.rs

@@ -86,7 +86,7 @@ impl SimplePool {
     /// The storage should be refunded to the user.
     pub fn share_unregister(&mut self, account_id: &AccountId) {
         let shares = self.shares.remove(account_id);
-        assert!(shares.expect(ERR13_LP_NOT_REGISTERED) == 0, "{}", ERR19_LP_NOT_EMPTY);
+        assert!(shares.expect(ERR13_LP_NOT_REGISTERED) == 0, "{}", ERR19_NONZERO_LP_SHARES);
     }
 
     /// Transfers shares from predecessor to receiver.

ref-exchange/src/stable_swap/mod.rs

@@ -629,7 +629,7 @@ impl StableSwapPool {
     /// The storage should be refunded to the user.
     pub fn share_unregister(&mut self, account_id: &AccountId) {
         let shares = self.shares.remove(account_id);
-        assert!(shares.expect(ERR13_LP_NOT_REGISTERED) == 0, "{}", ERR19_LP_NOT_EMPTY);
+        assert!(shares.expect(ERR13_LP_NOT_REGISTERED) == 0, "{}", ERR19_NONZERO_LP_SHARES);
     }
 
     /// Transfers shares from predecessor to receiver.