From 8a8f6f98775a50758123ae760bb020f833354e59 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Andr=C3=A9s=20Dorado=20Su=C3=A1rez?= 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 --- 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 f5c9e285ef3a..f18d4ed4e90b 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 { + /// 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")]