Repository: paritytech/substrate
File: frame/election-provider-support/src/lib.rs (Rust)

Code before:

	/// Elect a new set of winners, bounded by `MaxWinners` but an unbounded
	/// number of backers per winner. Data is fetched from
	/// [`ElectionProviderBase::DataProvider`]. An implementation could
	/// nonetheless impose its own custom limits.
	///
	/// The result is returned in a target major format, namely as *Bounded vector of
	/// support*.
	///
	/// This should be implemented as a self-weighing function. The implementor
	/// should register its appropriate weight at the end of execution with the
	/// system pallet directly.
	fn elect() -> Result<BoundedSupports<Self::AccountId, Self::MaxWinners>, Self::Error>;
}

pub trait ElectionProvider: ElectionProviderBase {
	/// Elect a new set of winners, without specifying any bounds on the amount
	/// of data fetched from [`ElectionProviderBase::DataProvider`].
	/// An implementation could nonetheless impose its own custom limits.
	///
	/// The result is returned in a target major format, namely as *vector of
	/// support*.
	///
	/// This should be implemented as a self-weighing function. The implementor
	/// should register its appropriate weight at the end of execution with the
	/// system pallet directly.
	fn elect() -> Result<Supports<Self::AccountId>, Self::Error>;
}

/// A sub-trait of the [`ElectionProvider`] for cases where we need to be sure
/// an election needs to happen instantly, not asynchronously.
///
/// The same `DataProvider` is assumed to be used.
///
/// Consequently, allows for control over the amount of data that is being
/// fetched from the [`ElectionProviderBase::DataProvider`].
pub trait InstantElectionProvider: ElectionProvider {
	/// Elect a new set of winners, but unlike [`ElectionProvider::elect`] which cannot enforce
	/// bounds, this trait method can enforce bounds on the amount of data provided by the
	/// `DataProvider`.
	///
	/// An implementing type, if itself bounded, should choose the minimum of the two bounds to
	/// choose the final value of `max_voters` and `max_targets`. In other words, an implementation
	/// should guarantee that `max_voter` and `max_targets` provided to this method are absolutely
	/// respected.
	fn elect_with_bounds(
		max_voters: usize,
		max_targets: usize,
	) -> Result<Supports<Self::AccountId>, Self::Error>;
}


Review comment (refactor):
```suggestion
	/// Same a [`BoundedElectionProvider`], but no bounds are imposed on the number of winners.
```

To avoid duplicate facts.

Also, I would move both of these docs to the trait, and leave the function to have a very small, rather rudimentary document like:

```
/// Perform the actual election process.
fn elect() -> ..
```



Code after:
}

/// Elect a new set of winners, bounded by `MaxWinners`.
///
/// Returns a result in bounded, target major format, namely as
/// *BoundedVec<(AccountId, Vec<Support>), MaxWinners>*.   
pub trait BoundedElectionProvider: ElectionProviderBase {
	/// The upper bound on election winners.
	type MaxWinners: Get<u32>;
	/// Performs the election. This should be implemented as a self-weighing function. The
	/// implementor should register its appropriate weight at the end of execution with the
	/// system pallet directly.
	fn elect() -> Result<BoundedSupports<Self::AccountId, Self::MaxWinners>, Self::Error>;
}

/// Same a [`BoundedElectionProvider`], but no bounds are imposed on the number
/// of winners.
///
/// The result is returned in a target major format, namely as
///*Vec<(AccountId, Vec<Support>)>*.
pub trait ElectionProvider: ElectionProviderBase {
	/// Performs the election. This should be implemented as a self-weighing
	/// function, similar to [`BoundedElectionProvider::elect()`].
	fn elect() -> Result<Supports<Self::AccountId>, Self::Error>;
}

/// A sub-trait of the [`ElectionProvider`] for cases where we need to be sure
/// an election needs to happen instantly, not asynchronously.
///
/// The same `DataProvider` is assumed to be used.
///
/// Consequently, allows for control over the amount of data that is being
/// fetched from the [`ElectionProviderBase::DataProvider`].
pub trait InstantElectionProvider: ElectionProvider {
	/// Elect a new set of winners, but unlike [`ElectionProvider::elect`] which cannot enforce
	/// bounds, this trait method can enforce bounds on the amount of data provided by the
	/// `DataProvider`.
	///
	/// An implementing type, if itself bounded, should choose the minimum of the two bounds to
	/// choose the final value of `max_voters` and `max_targets`. In other words, an implementation
	/// should guarantee that `max_voter` and `max_targets` provided to this method are absolutely
	/// respected.
	fn elect_with_bounds(
		max_voters: usize,
		max_targets: usize,
	) -> Result<Supports<Self::AccountId>, Self::Error>;
}

/// An election provider to be used only for testing.
#[cfg(feature = "std")]
pub struct NoElection<X>(sp_std::marker::PhantomData<X>);