Skip to content

chore(docs): unify rustdoc style across pallet-subtensor #2603

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
mcjkula wants to merge 7 commits into
base: devnet-ready
Choose a base branch
from
Draft

chore(docs): unify rustdoc style across pallet-subtensor #2603

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
e3abf8f
strip decorative separators from pallet-subtensor doc comments
mcjkula Apr 20, 2026
c35f571
normalize rustdoc section headings in pallet-subtensor
mcjkula Apr 20, 2026
b1d136d
replace extrinsic error prose with named `# Errors` bullets
mcjkula Apr 20, 2026
3917853
normalize event and error bullets to canonical quoted form
mcjkula Apr 20, 2026
77ce515
normalize inline `///` admonitions to canonical headings
mcjkula Apr 20, 2026
82f7793
place inline argument bullets under `# Arguments` heading
mcjkula Apr 20, 2026
e7ec631
normalize argument and return bullet format in pallet-subtensor
mcjkula Apr 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 20 additions & 21 deletions pallets/subtensor/src/coinbase/root.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@ impl<T: Config> Pallet<T> {
///
/// This function retrieves the total number of root network validators.
///
/// # Returns:
/// * 'u16': The total number of root network validators
/// # Returns
/// * `u16`: The total number of root network validators.
///
pub fn get_num_root_validators() -> u16 {
Self::get_subnetwork_n(NetUid::ROOT)
Expand All @@ -38,8 +38,8 @@ impl<T: Config> Pallet<T> {
///
/// This function retrieves the max validators count of root network.
///
/// # Returns:
/// * 'u16': The max validators count of root network.
/// # Returns
/// * `u16`: The max validators count of root network.
///
pub fn get_max_root_validators() -> u16 {
Self::get_max_allowed_uids(NetUid::ROOT)
Expand All @@ -49,11 +49,11 @@ impl<T: Config> Pallet<T> {
///
/// It's important to check for invalid UIDs to ensure data integrity and avoid referencing nonexistent subnets.
///
/// # Arguments:
/// * 'uids': A reference to a vector of UIDs to check.
/// # Arguments
/// * `uids`: A reference to a vector of UIDs to check.
///
/// # Returns:
/// * 'bool': 'true' if any of the UIDs are invalid, 'false' otherwise.
/// # Returns
/// * `bool`: 'true' if any of the UIDs are invalid, 'false' otherwise.
///
pub fn contains_invalid_root_uids(netuids: &[NetUid]) -> bool {
for netuid in netuids {
Expand All @@ -70,12 +70,12 @@ impl<T: Config> Pallet<T> {
/// This function is responsible for registering the hotkey of a user.
/// The root key with the least stake if pruned in the event of a filled network.
///
/// # Arguments:
/// * 'origin': Represents the origin of the call.
/// * 'hotkey': The hotkey that the user wants to register to the root network.
/// # Arguments
/// * `origin`: Represents the origin of the call.
/// * `hotkey`: The hotkey that the user wants to register to the root network.
///
/// # Returns:
/// * 'DispatchResult': A result type indicating success or failure of the registration.
/// # Returns
/// * `DispatchResult`: A result type indicating success or failure of the registration.
///
pub fn do_root_register(origin: OriginFor<T>, hotkey: T::AccountId) -> DispatchResult {
// --- 0. Get the unique identifier (UID) for the root network.
Expand Down Expand Up @@ -192,14 +192,14 @@ impl<T: Config> Pallet<T> {

/// Facilitates the removal of a user's subnetwork.
///
/// # Args:
/// * 'origin': ('T::RuntimeOrigin'): The calling origin. Must be signed.
/// * 'netuid': ('u16'): The unique identifier of the network to be removed.
/// # Arguments
/// * `origin`: ('T::RuntimeOrigin'): The calling origin. Must be signed.
/// * `netuid`: ('u16'): The unique identifier of the network to be removed.
///
/// # Event:
/// # Events
/// * 'NetworkRemoved': Emitted when a network is successfully removed.
///
/// # Raises:
/// # Errors
/// * 'MechanismDoesNotExist': If the specified network does not exist.
/// * 'NotSubnetOwner': If the caller does not own the specified subnet.
///
Expand Down Expand Up @@ -500,9 +500,8 @@ impl<T: Config> Pallet<T> {
///
/// If the calculated lock cost is less than the minimum lock cost, the minimum lock cost is returned.
///
/// # Returns:
/// * 'u64':
/// - The lock cost for the network.
/// # Returns
/// * `u64`: The lock cost for the network.
///
pub fn get_network_lock_cost() -> TaoBalance {
let last_lock = Self::get_network_last_lock();
Expand Down
10 changes: 5 additions & 5 deletions pallets/subtensor/src/coinbase/run_coinbase.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -780,9 +780,9 @@ impl<T: Config> Pallet<T> {
/// The hotkey also gets a portion based on its own stake contribution, this is added to the childkey take.
///
/// # Arguments
/// * `hotkye` - The hotkey to distribute out from.
/// * `netuid` - The netuid we are computing on.
/// * `dividends` - the dividends to distribute.
/// * `hotkye`: The hotkey to distribute out from.
/// * `netuid`: The netuid we are computing on.
/// * `dividends`: the dividends to distribute.
///
/// # Returns
/// * dividend_tuples: `Vec<(T::AccountId, u64)>` - Vector of (hotkey, divs) for each parent including self.
Expand Down Expand Up @@ -924,10 +924,10 @@ impl<T: Config> Pallet<T> {
/// Checks if the epoch should run for a given subnet based on the current block.
///
/// # Arguments
/// * `netuid` - The unique identifier of the subnet.
/// * `netuid`: The unique identifier of the subnet.
///
/// # Returns
/// * `bool` - True if the epoch should run, false otherwise.
/// * `bool`: True if the epoch should run, false otherwise.
pub fn should_run_epoch(netuid: NetUid, current_block: u64) -> bool {
Self::blocks_until_next_epoch(netuid, Self::get_tempo(netuid), current_block) == 0
}
Expand Down
4 changes: 3 additions & 1 deletion pallets/subtensor/src/epoch/math.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1350,7 +1350,9 @@ pub fn mat_vec_mul_sparse(
}

/// Clamp the input value between high and low.
/// Note: assumes high > low
///
/// # Note
/// Assumes `high > low`.
pub fn clamp_value(value: I32F32, low: I32F32, high: I32F32) -> I32F32 {
// First, clamp the value to ensure it does not exceed the upper bound (high).
// If the value is greater than 'high', it will be set to 'high'.
Expand Down
83 changes: 40 additions & 43 deletions pallets/subtensor/src/epoch/run_epoch.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -547,15 +547,12 @@ impl<T: Config> Pallet<T> {
/// Calculates reward consensus values, then updates rank, trust, consensus, incentive, dividend, pruning_score, emission and bonds, and
/// returns the emissions for uids/hotkeys in a given `netuid`.
///
/// # Args:
/// * 'netuid': ( u16 ):
/// - The network to distribute the emission onto.
/// # Arguments
/// * `netuid`: The network to distribute the emission onto.
///
/// * 'rao_emission': ( u64 ):
/// - The total emission for the epoch.
/// * `rao_emission`: The total emission for the epoch.
///
/// * 'debug' ( bool ):
/// - Print debugging outputs.
/// * `debug`: Print debugging outputs.
///
pub fn epoch_mechanism(
netuid: NetUid,
Expand Down Expand Up @@ -1194,12 +1191,12 @@ impl<T: Config> Pallet<T> {

/// Compute the Exponential Moving Average (EMA) of bonds using a normal alpha value for a sparse matrix.
///
/// # Args:
/// * `bonds_delta` - A vector of bond deltas.
/// * `bonds` - A vector of bonds.
/// * `netuid` - The network ID.
/// # Arguments
/// * `bonds_delta`: A vector of bond deltas.
/// * `bonds`: A vector of bonds.
/// * `netuid`: The network ID.
///
/// # Returns:
/// # Returns
/// A vector of EMA bonds.
pub fn compute_ema_bonds_normal_sparse(
bonds_delta: &[Vec<(u16, I32F32)>],
Expand Down Expand Up @@ -1230,12 +1227,12 @@ impl<T: Config> Pallet<T> {

/// Compute the Exponential Moving Average (EMA) of bonds using a normal alpha value.
///
/// # Args:
/// * `bonds_delta` - A vector of bond deltas.
/// * `bonds` - A vector of bonds.
/// * `netuid` - The network ID.
/// # Arguments
/// * `bonds_delta`: A vector of bond deltas.
/// * `bonds`: A vector of bonds.
/// * `netuid`: The network ID.
///
/// # Returns:
/// # Returns
/// A vector of EMA bonds.
pub fn compute_ema_bonds_normal(
bonds_delta: &[Vec<I32F32>],
Expand Down Expand Up @@ -1264,14 +1261,14 @@ impl<T: Config> Pallet<T> {

/// Compute the Exponential Moving Average (EMA) of bonds based on the Liquid Alpha setting
///
/// # Args:
/// * `netuid` - The network ID.
/// * `weights` - A vector of weights.
/// * `bonds` - A vector of bonds.
/// * `consensus` - A vector of consensus values.
/// * `active_stake` - A vector of active stake values.
/// # Arguments
/// * `netuid`: The network ID.
/// * `weights`: A vector of weights.
/// * `bonds`: A vector of bonds.
/// * `consensus`: A vector of consensus values.
/// * `active_stake`: A vector of active stake values.
///
/// # Returns:
/// # Returns
/// A vector of EMA bonds.
pub fn compute_bonds(
netuid: NetUid,
Expand Down Expand Up @@ -1304,14 +1301,14 @@ impl<T: Config> Pallet<T> {

/// Compute the Exponential Moving Average (EMA) of bonds based on the Liquid Alpha setting for a sparse matrix.
///
/// # Args:
/// * `netuid` - The network ID.
/// * `weights` - A vector of weights.
/// * `bonds` - A vector of bonds.
/// * `consensus` - A vector of consensus values.
/// * `active_stake` - A vector of active stake values.
/// # Arguments
/// * `netuid`: The network ID.
/// * `weights`: A vector of weights.
/// * `bonds`: A vector of bonds.
/// * `consensus`: A vector of consensus values.
/// * `active_stake`: A vector of active stake values.
///
/// # Returns:
/// # Returns
/// A vector of EMA bonds.
pub fn compute_bonds_sparse(
netuid_index: NetUidStorageIndex,
Expand Down Expand Up @@ -1347,13 +1344,13 @@ impl<T: Config> Pallet<T> {
/// Compute liquid alphas matrix
/// There is a separate alpha param for each validator-miner binding
///
/// # Args:
/// * `netuid` - The network ID.
/// * `weights` - A vector of weights.
/// * `bonds` - A vector of bonds.
/// * `consensus` - A vector of consensus values.
/// # Arguments
/// * `netuid`: The network ID.
/// * `weights`: A vector of weights.
/// * `bonds`: A vector of bonds.
/// * `consensus`: A vector of consensus values.
///
/// # Returns:
/// # Returns
/// A matrix of alphas
pub fn compute_liquid_alpha_values(
netuid: NetUid,
Expand Down Expand Up @@ -1400,13 +1397,13 @@ impl<T: Config> Pallet<T> {
/// Compute liquid alphas sparse matrix
/// There is a separate alpha param for each validator-miner binding
///
/// # Args:
/// * `netuid` - The network ID.
/// * `weights` - A vector of weights.
/// * `bonds` - A vector of bonds.
/// * `consensus` - A vector of consensus values.
/// # Arguments
/// * `netuid`: The network ID.
/// * `weights`: A vector of weights.
/// * `bonds`: A vector of bonds.
/// * `consensus`: A vector of consensus values.
///
/// # Returns:
/// # Returns
/// A dense matrix of alphas
pub fn compute_liquid_alpha_values_sparse(
netuid: NetUid,
Expand Down
Loading