Format / fix cw3 spec details

packages/cw3/src/msg.rs

@@ -39,8 +39,8 @@ pub enum Vote {
     No,
     /// Marks participation but does not count towards the ratio of support / opposed
     Abstain,
-    /// Veto is generally to be treated as a no vote. Some implementations may allow certain
-    /// voters to be able to Veto, or them to be counted stronger then nos in some way.
+    /// Veto is generally to be treated as a No vote. Some implementations may allow certain
+    /// voters to be able to Veto, or them to be counted stronger than No in some way.
     Veto,
 }
 

packages/cw3/src/query.rs

@@ -69,44 +69,47 @@ pub enum ThresholdResponse {
     /// A proposal of this type can pass early as soon as the needed weight of yes votes has been cast.
     AbsoluteCount { weight: u64, total_weight: u64 },
 
-    /// Declares a percentage of the total weight that must cast yes votes in order for
-    /// a proposal to pass. As with `AbsoluteCount`, it only matters the sum of yes votes.
+    /// Declares a percentage of the total weight that must cast Yes votes, in order for
+    /// a proposal to pass. As with `AbsoluteCount`, Yes votes are the only ones that count.
     ///
     /// This is useful for similar circumstances as `AbsoluteCount`, where we have a relatively
-    /// small set of voters and participation is required. The advantage here is that if the
-    /// voting set (group) changes between proposals, the number of votes needed is adjusted
-    /// accordingly.
+    /// small set of voters, and participation is required.
+    /// It is understood that if the voting set (group) changes between different proposals that
+    /// refer to the same group, each proposal will work with a different set of voter weights
+    /// (the ones snapshotted at proposal creation), and the passing weight for each proposal
+    /// will be computed based on the absolute percentage, times the total weights of the members
+    /// at the time of each proposal creation.
     ///
     /// Example: we set `percentage` to 51%. Proposal 1 starts when there is a `total_weight` of 5.
-    /// This will require 3 weight of yes votes in order to pass. Later, the Proposal 2 starts but the
+    /// This will require 3 weight of Yes votes in order to pass. Later, the Proposal 2 starts but the
     /// `total_weight` of the group has increased to 9. That proposal will then automatically
-    /// require 5 yes of 9 to pass, rather than 3 yes of 9 as would be the case with `AbsoluteCount`.
-    ///
-    /// A proposal of this type can pass early as soon as the needed weight of yes votes has been cast.
+    /// require 5 Yes of 9 to pass, rather than 3 yes of 9 as would be the case with `AbsoluteCount`.
     AbsolutePercentage {
         percentage: Decimal,
         total_weight: u64,
     },
 
-    /// Declares a `quorum` of the total votes that must participate in the election in order
-    /// for the vote to be considered at all. Within the votes that were cast, it requires `threshold`
-    /// in favor. That is calculated by ignoring the abstain votes (they count towards `quorum`
-    /// but do not influence `threshold`). That is, we calculate `yes / (yes + no + veto)`
-    /// and compare that with `threshold` to consider if the proposal was passed.
+    /// In addition to a `threshold`, declares a `quorum` of the total votes that must participate
+    /// in the election in order for the vote to be considered at all. Within the votes that
+    /// were cast, it requires `threshold` votes in favor. That is calculated by ignoring
+    /// the Abstain votes (they count towards `quorum`, but do not influence `threshold`).
+    /// That is, we calculate `Yes / (Yes + No + Veto)` and compare it with `threshold` to consider
+    /// if the proposal was passed.
     ///
     /// It is rather difficult for a proposal of this type to pass early. That can only happen if
-    /// the required quorum has been already met, and in the case if all remaining voters were
-    /// to vote no, the threshold would still be met.
+    /// the required quorum has been already met, and there are already enough Yes votes for the
+    /// proposal to pass.
     ///
-    /// 30% yes votes, 10% no votes, and 20% abstain would pass early if quorum <= 60%
+    /// 30% Yes votes, 10% No votes, and 20% Abstain would pass early if quorum <= 60%
     /// (who has cast votes) and if the threshold is <= 37.5% (the remaining 40% voting
     /// no => 30% yes + 50% no). Once the voting period has passed with no additional votes,
     /// that same proposal would be considered successful if quorum <= 60% and threshold <= 75%
     /// (percent in favor if we ignore abstain votes).
     ///
-    /// This type is more common in general elections where participation is expected to often
-    /// be low, and `AbsolutePercentage` would either be too restrictive to pass anything,
-    /// or allow low percentages to pass if there was high participation in one election.
+    /// This type is more common in general elections, where participation is often expected to
+    /// be low, and `AbsolutePercentage` would either be too high to pass anything,
+    /// or allow low percentages to pass, independently of if there was high participation in the
+    /// election or not.
     ThresholdQuora {
         threshold: Decimal,
         quorum: Decimal,