From 8a8f6f98775a50758123ae760bb020f833354e59 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pablo=20Andr=C3=A9s=20Dorado=20Su=C3=A1rez?=
<hola@pablodorado.com>
Date: Wed, 31 Jan 2024 14:59:47 -0500
Subject: [PATCH] [Documentation] Add description for VoteTally's methods
(#3140)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
# Description
While methods' names on [`VoteTally`][1] trait might be self-explanatory
at first sight, the distinction between `support` and `approval` can be
a bit ambiguous for some readers. This PR aims to clarify the
distinction and inform about the expected values for every not yet
documented method on this trait.
# Checklist
- [x] My PR includes a detailed description as outlined in the
"Description" section above
- [ ] My PR follows the [labeling requirements](CONTRIBUTING.md#Process)
of this project (at minimum one label for `T`
required)
- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works (if applicable)
[1]:
https://docs.rs/frame-support/latest/frame_support/traits/trait.VoteTally.html
---------
Co-authored-by: Bastian Köcher <git@kchr.de>
---
substrate/frame/support/src/traits/voting.rs | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/substrate/frame/support/src/traits/voting.rs b/substrate/frame/support/src/traits/voting.rs
index f5c9e285ef3..f18d4ed4e90 100644
--- a/substrate/frame/support/src/traits/voting.rs
+++ b/substrate/frame/support/src/traits/voting.rs
@@ -25,14 +25,24 @@ use sp_runtime::{traits::Member, DispatchError};
use sp_std::prelude::*;
pub trait VoteTally<Votes, Class> {
+ /// Initializes a new tally.
fn new(_: Class) -> Self;
+ /// Returns the number of positive votes for the tally.
fn ayes(&self, class: Class) -> Votes;
+ /// Returns the approval ratio (positive to total votes) for the tally, without multipliers
+ /// (e.g. conviction, ranks, etc.).
fn support(&self, class: Class) -> Perbill;
+ /// Returns the approval ratio (positive to total votes) for the tally.
fn approval(&self, class: Class) -> Perbill;
+ /// Returns an instance of the tally representing a unanimous approval, for benchmarking
+ /// purposes.
#[cfg(feature = "runtime-benchmarks")]
fn unanimity(class: Class) -> Self;
+ /// Returns an instance of the tally representing a rejecting state, for benchmarking purposes.
#[cfg(feature = "runtime-benchmarks")]
fn rejection(class: Class) -> Self;
+ /// Returns an instance of the tally given some `approval` and `support`, for benchmarking
+ /// purposes.
#[cfg(feature = "runtime-benchmarks")]
fn from_requirements(support: Perbill, approval: Perbill, class: Class) -> Self;
#[cfg(feature = "runtime-benchmarks")]
--
GitLab