chore(*): clean up iota-names packages (#450)

* clean up auction module

* clean up coupons module

* clean up payments module

* clean up subnames module

* clean up iota-names constants

* clean up iota-names deny list

* clean up iota-names name_registration

* clean up iota-names name

* clean up iota-names registry

* clean up iota-names validation

* clean up iota-names sales

* don't mention internal functions in function docs

* sssss

* review suggestions

Co-authored-by: DaughterOfMars <chloedaughterofmars@gmail.com>

* review suggestions

Co-authored-by: DaughterOfMars <chloedaughterofmars@gmail.com>

* reorder

---------

Co-authored-by: DaughterOfMars <chloedaughterofmars@gmail.com>

Author: Alex6323

packages/auction/sources/auction.move

@@ -2,7 +2,6 @@
 // Modifications Copyright (c) 2025 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
-/// Implementation of auction module.
 module iota_names_auction::auction;
 
 use iota::balance::{Self, Balance};
@@ -29,6 +28,7 @@ const AUCTION_BIDDING_PERIOD_MS: u64 = 60 * 60 * 1000;
 const AUCTION_MIN_QUIET_PERIOD_MS: u64 = 10 * 60 * 1000;
 /// The overbid must be at least of 1 IOTA, which is 10^9 NANOs
 const AUCTION_MIN_OVERBID_VALUE_IOTA: u64 = 1_000_000_000;
+
 // === Abort codes ===
 
 #[error]
@@ -51,14 +51,14 @@ const ENoProfits: vector<u8> = b"There are no profits to withdraw.";
 /// Authorization witness to call protected functions of `iota_names`.
 public struct AuctionAuth has drop {}
 
-/// The AuctionHouse application.
+/// The `AuctionHouse` application.
 public struct AuctionHouse has key, store {
     id: UID,
     balance: Balance<IOTA>,
     auctions: LinkedTable<Name, Auction>,
 }
 
-/// The Auction application.
+/// The `Auction` application.
 #[allow(lint(coin_field))]
 public struct Auction has store {
     name: Name,
@@ -77,7 +77,8 @@ fun init(ctx: &mut TxContext) {
     });
 }
 
-/// Start an auction if it's not started yet; and make the first bid.
+/// Start an auction for a name by placing the first bid.
+/// This will fail if the name is not available or already being auctioned.
 public fun start_auction_and_place_bid(
     self: &mut AuctionHouse,
     iota_names: &mut IotaNames,
@@ -121,13 +122,14 @@ public fun start_auction_and_place_bid(
     self.auctions.push_front(name, auction)
 }
 
-/// #### Notice
 /// Bidders use this function to place a new bid.
 ///
-/// Panics
-/// Panics if `name` is invalid
-/// or there isn't an auction for `name`
-/// or `bid` is too low,
+/// ### Panics
+/// 
+/// Panics if:
+/// - the name is invalid
+/// - there is no auction for the name
+/// - the bid is too low
 public fun place_bid(
     self: &mut AuctionHouse,
     name: String,
@@ -201,11 +203,11 @@ public fun place_bid(
     self.auctions.push_front(name, auction);
 }
 
-/// #### Notice
-/// Auction winner can come and claim the NFT
+/// Auction winners can use this function to claim the NFT associated with the name.
 ///
-/// Panics
-/// sender is not the winner
+/// ### Panics
+/// 
+/// Panics if the sender is not the winner.
 public fun claim(
     self: &mut AuctionHouse,
     name: String,
@@ -245,11 +247,7 @@ public fun claim(
 
 // === Public Functions ===
 
-/// #### Notice
-/// Get metadata of an auction
-///
-/// #### Params
-/// The name being auctioned.
+/// Get metadata of an auction.
 ///
 /// #### Return
 /// (`start_timestamp_ms`, `end_timestamp_ms`, `current_bidder`, `highest_amount`)
@@ -290,6 +288,11 @@ public fun collect_winning_auction_fund(
 
 // === Admin Functions ===
 
+/// Admin functionality used to withdraw all funds from the auction house.
+/// 
+/// ### Panics
+/// 
+/// Panics if the auction house has no profits.
 public fun admin_withdraw_funds(
     _: &AdminCap,
     self: &mut AuctionHouse,

packages/coupons/sources/coupons.move

@@ -25,13 +25,9 @@ public struct Coupons has store {
     coupons: Table<vector<u8>, Coupon>,
 }
 
-public(package) fun new(ctx: &mut TxContext): Coupons {
-    Coupons {
-        coupons: table::new(ctx),
-    }
-}
+// === Public functions ===
 
-// Add percentaged based coupon.
+/// Adds percentaged based coupon.
 public fun add_percentage_coupon(
     self: &mut Coupons,
     hash: String,
@@ -41,7 +37,7 @@ public fun add_percentage_coupon(
     self.save_coupon(hash, coupon::new_percentage(percentage, rules));
 }
 
-// Add fixed amount coupon.
+/// Adds fixed amount coupon.
 public fun add_fixed_coupon(
     self: &mut Coupons,
     hash: String,
@@ -51,25 +47,35 @@ public fun add_fixed_coupon(
     self.save_coupon(hash, coupon::new_fixed(amount, rules));
 }
 
-// A function to remove a coupon from the system.
+// === Internal functions ===
+
+/// Creates the `Coupons` struct.
+public(package) fun new(ctx: &mut TxContext): Coupons {
+    Coupons {
+        coupons: table::new(ctx),
+    }
+}
+
+/// Removes a coupon from the system.
 public(package) fun remove_coupon(self: &mut Coupons, hash: String) {
     let hash = hex::decode(hash.into_bytes());
     assert!(self.coupons.contains(hash), ECouponDoesNotExist);
     let _: Coupon = self.coupons.remove(hash);
 }
 
-/// Private internal functions
-/// An internal function to save the coupon in the shared object's config.
+/// Saves the coupon in the shared object's config.
 public(package) fun save_coupon(self: &mut Coupons, hash: String, coupon: Coupon) {
     let hash = hex::decode(hash.into_bytes());
     assert!(!self.coupons.contains(hash), ECouponAlreadyExists);
     self.coupons.add(hash, coupon);
 }
 
+/// Returns a reference to the coupon table.
 public(package) fun coupons(self: &Coupons): &Table<vector<u8>, Coupon> {
     &self.coupons
 }
 
+/// Returns a mutable reference to the coupon table.
 public(package) fun coupons_mut(self: &mut Coupons): &mut Table<vector<u8>, Coupon> {
     &mut self.coupons
 }

packages/iota-names/sources/constants.move

@@ -15,19 +15,18 @@ use std::string::String;
 const IOTA_TLN: vector<u8> = b"iota";
 /// The amount of milliseconds in a year.
 const YEAR_MS: u64 = 365 * 24 * 60 * 60 * 1000;
-/// 30 day Grace period in milliseconds.
+/// 30 day grace period in milliseconds.
 const GRACE_PERIOD_MS: u64 = 30 * 24 * 60 * 60 * 1000;
 
 /// A leaf record doesn't expire. Expiration is retrieved by the parent's
 /// expiration.
 const LEAF_EXPIRATION_TIMESTAMP: u64 = 0;
 
-/// Subname constants
-///
-/// These constants are the core of the subname functionality.
-/// Even if we decide to change the subname module, these can
-/// be re-used. They're added as metadata on NameRecord.
-///
+// === Subname constants ===
+// These constants are the core of the subname functionality.
+// Even if we decide to change the subname module, these can
+// be re-used. They're added as metadata on `NameRecord`.
+
 /// Whether a parent name can create child names. (name -> subname)
 const ALLOW_CREATION: vector<u8> = b"S_AC";
 /// Whether a child-name can auto-renew (if the parent hasn't changed).
@@ -44,7 +43,6 @@ public fun year_ms(): u64 { YEAR_MS }
 /// Grace period in milliseconds after which the name expires.
 public fun grace_period_ms(): u64 { GRACE_PERIOD_MS }
 
-/// Subname constants
 /// The NameRecord key that a subname can create child names.
 public fun subname_allow_creation_key(): String { ALLOW_CREATION.to_string() }
 

packages/iota-names/sources/controller.move

@@ -47,7 +47,7 @@ public fun set_target_address(
     registry.set_target_address(name, new_target);
 }
 
-/// Set the reverse lookup address for the name
+/// Sets the reverse lookup address for the name.
 public fun set_reverse_lookup(
     iota_names: &mut IotaNames,
     name: String,

packages/iota-names/sources/deny_list.move

@@ -23,6 +23,7 @@ public struct DenyList has store {
 /// Authorization witness to call protected functions of `iota_names`.
 public struct DenyListAuth has drop {}
 
+/// Sets up the deny list as admin.
 public fun setup(iota_names: &mut IotaNames, cap: &AdminCap, ctx: &mut TxContext) {
     iota_names::add_registry(
         cap,
@@ -34,7 +35,7 @@ public fun setup(iota_names: &mut IotaNames, cap: &AdminCap, ctx: &mut TxContext
     );
 }
 
-/// Check for a reserved name.
+/// Checks for a reserved name.
 public fun is_reserved_name(iota_names: &IotaNames, name: &Name): bool {
     let len = name.number_of_levels();
     let mut index = 1;
@@ -64,39 +65,39 @@ public fun is_blocked_name(iota_names: &IotaNames, name: &Name): bool {
     false
 }
 
-/// Add a list of reserved labels to the list as admin.
+/// Adds a list of reserved labels to the list as admin.
 public fun add_reserved_labels(iota_names: &mut IotaNames, _: &AdminCap, labels: vector<String>) {
     internal_add_labels_to_list(
         &mut deny_list_mut(iota_names).reserved,
         labels,
     );
 }
 
-/// Add a list of blocked labels to the list as admin.
+/// Adds a list of blocked labels to the list as admin.
 public fun add_blocked_labels(iota_names: &mut IotaNames, _: &AdminCap, labels: vector<String>) {
     internal_add_labels_to_list(
         &mut deny_list_mut(iota_names).blocked,
         labels,
     );
 }
 
-/// Remove a list of labels from the reserved list as admin.
+/// Removes a list of labels from the reserved list as admin.
 public fun remove_reserved_labels(iota_names: &mut IotaNames, _: &AdminCap, labels: vector<String>) {
     internal_remove_labels_from_list(
         &mut deny_list_mut(iota_names).reserved,
         labels,
     );
 }
 
-/// Remove a list of labels from the blocked list as admin.
+/// Removes a list of labels from the blocked list as admin.
 public fun remove_blocked_names(iota_names: &mut IotaNames, _: &AdminCap, labels: vector<String>) {
     internal_remove_labels_from_list(
         &mut deny_list_mut(iota_names).blocked,
         labels,
     );
 }
 
-/// Get immutable access to the registry.
+/// Gets immutable access to the registry.
 fun deny_list(iota_names: &IotaNames): &DenyList {
     iota_names.registry()
 }

packages/iota-names/sources/name.move

@@ -4,8 +4,8 @@
 
 /// Defines the `Name` type and helper functions.
 ///
-/// Names are structured similar to web2 domains and the rules
-/// determining what a valid name is can be found here:
+/// Names are structured similar to web2 domains, and the rules
+/// determining what constitutes a valid name can be found here:
 /// https://en.wikipedia.org/wiki/Domain_name#Domain_name_syntax
 module iota_names::name;
 
@@ -32,7 +32,7 @@ public struct Name has copy, drop, store {
     labels: vector<String>,
 }
 
-// Construct a `Name` by parsing and validating the provided string
+// Constructs a `Name` by parsing and validating the provided string.
 public fun new(name: String): Name {
     assert!(name.length() <= MAX_NAME_LENGTH, EInvalidName);
 
@@ -79,27 +79,36 @@ public fun label(self: &Name, level: u64): &String {
 
 /// Returns the TLN (Top-Level Name) of a `Name`.
 ///
-/// "name.iota" -> "iota"
+/// e.g. `name.iota` -> `iota`
 public fun tln(self: &Name): &String {
     label(self, 0)
 }
 
 /// Returns the SLN (Second-Level Name) of a `Name`.
 ///
-/// "name.iota" -> "iota"
+/// e.g. `name.iota` -> `name`
 public fun sln(self: &Name): &String {
     label(self, 1)
 }
 
+/// Returns the number of labels of a `Name` (TLN included).
+/// 
+/// e.g. `name.iota` -> 2
 public fun number_of_levels(self: &Name): u64 {
     self.labels.length()
 }
 
+/// Returns whether the name is a subname.
+/// 
+/// e.g.
+/// `name.iota` -> `false`, 
+/// `subname.name.iota` -> `true`
 public fun is_subname(name: &Name): bool {
     number_of_levels(name) > 2
 }
 
-/// Derive the parent of a subname.
+/// Derives the parent of a subname.
+/// 
 /// e.g. `subname.example.iota` -> `example.iota`
 public fun parent(name: &Name): Option<Name> {
     if (is_subname(name)) {
@@ -115,7 +124,9 @@ public fun parent(name: &Name): Option<Name> {
     }
 }
 
-/// Checks if `parent` name is a valid parent for `child`.
+/// Checks if the given `parent` name is valid for the given `child` name.
+/// 
+/// e.g. (`example.iota`, `subname.example.iota`) -> `true`
 public fun is_parent_of(parent: &Name, child: &Name): bool {
     if (number_of_levels(parent) < number_of_levels(child)) {
         let mut maybe_parent = parent(child);

packages/iota-names/sources/name_registration.move

@@ -3,15 +3,8 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /// Handles creation of the `NameRegistration`s. Separates the logic of
-/// creating
-/// a `NameRegistration`. New `NameRegistration`s can be created only by the
-/// `registry` and this module is tightly coupled with it.
-///
-/// When reviewing the module, make sure that:
-///
-/// - mutable functions can't be called directly by the owner
-/// - all getters are public and take an immutable reference
-///
+/// creating a `NameRegistration`. New `NameRegistration`s can be created 
+/// only by the `registry` and this module is tightly coupled with it.
 module iota_names::name_registration;
 
 use iota::clock::{timestamp_ms, Clock};
@@ -98,7 +91,7 @@ public fun expiration_timestamp_ms(self: &NameRegistration): u64 {
     self.expiration_timestamp_ms
 }
 
-// get a read-only `uid` field of `NameRegistration`.
+// Returns a read-only `uid` field of `NameRegistration`.
 public fun uid(self: &NameRegistration): &UID { &self.id }
 
 /// Get the mutable `id` field of the `NameRegistration`.