Skip to content

Commit

Permalink
fix: update natspec of TokenVoting.sol
Browse files Browse the repository at this point in the history
  • Loading branch information
@Rekard0
Rekard0 committed Nov 12, 2024
1 parent f92c1e0 commit 8d1dce9
Show file tree
Hide file tree
Showing 5 changed files with 49 additions and 44 deletions.
24 changes: 12 additions & 12 deletions packages/contracts/src/IMajorityVoting.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ pragma solidity ^0.8.8;
interface IMajorityVoting {
/// @notice Vote options that a voter can chose from.
/// @param None The default option state of a voter indicating the absence from the vote.
/// This option neither influences support nor participation.
/// This option neither influences support nor participation.
/// @param Abstain This option does not influence the support but counts towards participation.
/// @param Yes This option increases the support and counts towards participation.
/// @param No This option decreases the support and counts towards participation.
Expand Down Expand Up @@ -45,30 +45,30 @@ interface IMajorityVoting {
function minParticipation() external view returns (uint32);

/// @notice Checks if the support value defined as:
/// $$\texttt{support} = \frac{N_\text{yes}}{N_\text{yes}+N_\text{no}}$$
/// for a proposal is greater than the support threshold.
/// $$\texttt{support} = \frac{N_\text{yes}}{N_\text{yes}+N_\text{no}}$$
/// for a proposal is greater than the support threshold.
/// @param _proposalId The ID of the proposal.
/// @return Returns `true` if the support is greater than the support threshold and `false` otherwise.
function isSupportThresholdReached(uint256 _proposalId) external view returns (bool);

/// @notice Checks if the worst-case support value defined as:
/// $$\texttt{worstCaseSupport} = \frac{N_\text{yes}}{ N_\text{total}-N_\text{abstain}}$$
/// for a proposal is greater than the support threshold.
/// $$\texttt{worstCaseSupport} = \frac{N_\text{yes}}{ N_\text{total}-N_\text{abstain}}$$
/// for a proposal is greater than the support threshold.
/// @param _proposalId The ID of the proposal.
/// @return Returns `true` if the worst-case support is greater than the support threshold and `false` otherwise.
function isSupportThresholdReachedEarly(uint256 _proposalId) external view returns (bool);

/// @notice Checks if the participation value defined as:
/// $$\texttt{participation} = \frac{N_\text{yes}+N_\text{no}+N_\text{abstain}}{N_\text{total}}$$
/// for a proposal is greater or equal than the minimum participation value.
/// $$\texttt{participation} = \frac{N_\text{yes}+N_\text{no}+N_\text{abstain}}{N_\text{total}}$$
/// for a proposal is greater or equal than the minimum participation value.
/// @param _proposalId The ID of the proposal.
/// @return Returns `true` if the participation is greater or equal than the minimum participation,
/// and `false` otherwise.
/// and `false` otherwise.
function isMinParticipationReached(uint256 _proposalId) external view returns (bool);

/// @notice Checks if the min approval value defined as:
///$$\texttt{minApproval} = \frac{N_\text{yes}}{N_\text{total}}$$
/// for a proposal is greater or equal than the minimum approval value.
/// $$\texttt{minApproval} = \frac{N_\text{yes}}{N_\text{total}}$$
/// for a proposal is greater or equal than the minimum approval value.
/// @param _proposalId The ID of the proposal.
/// @return Returns `true` if the approvals is greater or equal than the minimum approval and `false` otherwise.
function isMinApprovalReached(uint256 _proposalId) external view returns (bool);
Expand Down Expand Up @@ -99,7 +99,7 @@ interface IMajorityVoting {
/// @param _proposalId The ID of the proposal.
/// @param _voteOption The chosen vote option.
/// @param _tryEarlyExecution If `true`, early execution is tried after the vote cast.
/// The call does not revert if early execution is not possible.
/// The call does not revert if early execution is not possible.
function vote(uint256 _proposalId, VoteOption _voteOption, bool _tryEarlyExecution) external;

/// @notice Executes a proposal.
Expand All @@ -111,7 +111,7 @@ interface IMajorityVoting {
/// @param _account The account address to be checked.
/// @return The vote option cast by a voter for a certain proposal.
/// @dev May return `none` if the `_proposalId` do not exist,
/// or the `_account` does not have voting power.
/// or the `_account` does not have voting power.
function getVoteOption(
uint256 _proposalId,
address _account
Expand Down
49 changes: 26 additions & 23 deletions packages/contracts/src/MajorityVotingBase.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ import {IMajorityVoting} from "./IMajorityVoting.sol";
/// $$
///
/// Accordingly, early execution is possible when the vote is open,
/// the modified support criterion, and the particicpation criterion are met.
/// the modified support criterion, and the particicpation criterion are met.
/// @dev This contract implements the `IMajorityVoting` interface.
/// @custom:security-contact [email protected]
abstract contract MajorityVotingBase is
Expand All @@ -132,9 +132,9 @@ abstract contract MajorityVotingBase is
/// @notice The different voting modes available.
/// @param Standard In standard mode, early execution and vote replacement are disabled.
/// @param EarlyExecution In early execution mode, a proposal can be executed
/// early before the end date if the vote outcome cannot mathematically change by more voters voting.
/// early before the end date if the vote outcome cannot mathematically change by more voters voting.
/// @param VoteReplacement In vote replacement mode, voters can change their vote
/// multiple times and only the latest vote option is tallied.
/// multiple times and only the latest vote option is tallied.
enum VotingMode {
Standard,
EarlyExecution,
Expand All @@ -143,15 +143,15 @@ abstract contract MajorityVotingBase is

/// @notice A container for the majority voting settings that will be applied as parameters on proposal creation.
/// @param votingMode A parameter to select the vote mode.
/// In standard mode (0), early execution and vote replacement are disabled.
/// In early execution mode (1), a proposal can be executed early before the end date
/// if the vote outcome cannot mathematically change by more voters voting.
/// In vote replacement mode (2), voters can change their vote multiple times
/// and only the latest vote option is tallied.
/// In standard mode (0), early execution and vote replacement are disabled.
/// In early execution mode (1), a proposal can be executed early before the end date
/// if the vote outcome cannot mathematically change by more voters voting.
/// In vote replacement mode (2), voters can change their vote multiple times
/// and only the latest vote option is tallied.
/// @param supportThreshold The support threshold value.
/// Its value has to be in the interval [0, 10^6] defined by `RATIO_BASE = 10**6`.
/// Its value has to be in the interval [0, 10^6] defined by `RATIO_BASE = 10**6`.
/// @param minParticipation The minimum participation value.
/// Its value has to be in the interval [0, 10^6] defined by `RATIO_BASE = 10**6`.
/// Its value has to be in the interval [0, 10^6] defined by `RATIO_BASE = 10**6`.
/// @param minDuration The minimum duration of the proposal vote in seconds.
/// @param minProposerVotingPower The minimum voting power required to create a proposal.
struct VotingSettings {
Expand All @@ -169,12 +169,12 @@ abstract contract MajorityVotingBase is
/// @param voters The votes casted by the voters.
/// @param actions The actions to be executed when the proposal passes.
/// @param allowFailureMap A bitmap allowing the proposal to succeed, even if individual actions might revert.
/// If the bit at index `i` is 1, the proposal succeeds even if the `i`th action reverts.
/// A failure map value of 0 requires every action to not revert.
/// If the bit at index `i` is 1, the proposal succeeds even if the `i`th action reverts.
/// A failure map value of 0 requires every action to not revert.
/// @param minApprovalPower The minimum amount of yes votes power needed for the proposal advance.
/// @param targetConfig Configuration for the execution target, specifying the target address and operation type
/// (either `Call` or `DelegateCall`). Defined by `TargetConfig` in the `IPlugin` interface,
/// part of the `osx-commons-contracts` package, added in build 3.
/// (either `Call` or `DelegateCall`). Defined by `TargetConfig` in the `IPlugin` interface,
/// part of the `osx-commons-contracts` package, added in build 3.
struct Proposal {
bool executed;
ProposalParameters parameters;
Expand All @@ -189,7 +189,7 @@ abstract contract MajorityVotingBase is
/// @notice A container for the proposal parameters at the time of proposal creation.
/// @param votingMode A parameter to select the vote mode.
/// @param supportThreshold The support threshold value.
/// The value has to be in the interval [0, 10^6] defined by `RATIO_BASE = 10**6`.
/// The value has to be in the interval [0, 10^6] defined by `RATIO_BASE = 10**6`.
/// @param startDate The start date of the proposal vote.
/// @param endDate The end date of the proposal vote.
/// @param snapshotBlock The number of the block prior to the proposal creation.
Expand Down Expand Up @@ -373,6 +373,7 @@ abstract contract MajorityVotingBase is
}

/// @inheritdoc IProposal
/// @dev Requires the `EXECUTE_PROPOSAL_PERMISSION_ID` permission.
function execute(
uint256 _proposalId
) public virtual override(IMajorityVoting, IProposal) auth(EXECUTE_PROPOSAL_PERMISSION_ID) {
Expand Down Expand Up @@ -541,6 +542,7 @@ abstract contract MajorityVotingBase is
}

/// @notice Updates the voting settings.
/// @dev Requires the `UPDATE_VOTING_SETTINGS_PERMISSION_ID` permission.
/// @param _votingSettings The new voting settings.
function updateVotingSettings(
VotingSettings calldata _votingSettings
Expand All @@ -549,6 +551,7 @@ abstract contract MajorityVotingBase is
}

/// @notice Updates the minimal approval value.
/// @dev Requires the `UPDATE_VOTING_SETTINGS_PERMISSION_ID` permission.
/// @param _minApprovals The new minimal approval value.
function updateMinApprovals(
uint256 _minApprovals
Expand All @@ -560,16 +563,16 @@ abstract contract MajorityVotingBase is
/// @param _metadata The metadata of the proposal.
/// @param _actions The actions that will be executed after the proposal passes.
/// @param _allowFailureMap Allows proposal to succeed even if an action reverts.
/// Uses bitmap representation.
/// If the bit at index `x` is 1, the tx succeeds even if the action at `x` failed.
/// Passing 0 will be treated as atomic execution.
/// Uses bitmap representation.
/// If the bit at index `x` is 1, the tx succeeds even if the action at `x` failed.
/// Passing 0 will be treated as atomic execution.
/// @param _startDate The start date of the proposal vote.
/// If 0, the current timestamp is used and the vote starts immediately.
/// If 0, the current timestamp is used and the vote starts immediately.
/// @param _endDate The end date of the proposal vote.
/// If 0, `_startDate + minDuration` is used.
/// If 0, `_startDate + minDuration` is used.
/// @param _voteOption The chosen vote option to be casted on proposal creation.
/// @param _tryEarlyExecution If `true`, early execution is tried after the vote cast.
/// The call does not revert if early execution is not possible.
/// The call does not revert if early execution is not possible.
/// @return proposalId The ID of the proposal.
function createProposal(
bytes calldata _metadata,
Expand All @@ -585,7 +588,7 @@ abstract contract MajorityVotingBase is
/// @param _proposalId The ID of the proposal.
/// @param _voteOption The chosen vote option to be casted on the proposal vote.
/// @param _tryEarlyExecution If `true`, early execution is tried after the vote cast.
/// The call does not revert if early execution is not possible.
/// The call does not revert if early execution is not possible.
function _vote(
uint256 _proposalId,
VoteOption _voteOption,
Expand Down Expand Up @@ -738,7 +741,7 @@ abstract contract MajorityVotingBase is

/// @notice Validates and returns the proposal dates.
/// @param _start The start date of the proposal.
/// If 0, the current timestamp is used and the vote starts immediately.
/// If 0, the current timestamp is used and the vote starts immediately.
/// @param _end The end date of the proposal. If 0, `_start + minDuration` is used.
/// @return startDate The validated start date of the proposal.
/// @return endDate The validated end date of the proposal.
Expand Down
12 changes: 7 additions & 5 deletions packages/contracts/src/TokenVoting.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ import {Action} from "@aragon/osx-commons-contracts/src/executors/IExecutor.sol"
import {MajorityVotingBase} from "./MajorityVotingBase.sol";

/// @title TokenVoting
/// @author Aragon X - 2021-2023
/// @author Aragon X - 2021-2024
/// @notice The majority voting implementation using an
/// [OpenZeppelin `Votes`](https://docs.openzeppelin.com/contracts/4.x/api/governance#Votes)
/// compatible governance token.
Expand All @@ -30,7 +30,7 @@ contract TokenVoting is IMembership, MajorityVotingBase {
bytes4 internal constant TOKEN_VOTING_INTERFACE_ID = this.getVotingToken.selector;

/// @notice An [OpenZeppelin `Votes`](https://docs.openzeppelin.com/contracts/4.x/api/governance#Votes)
/// compatible contract referencing the token being used for voting.
/// compatible contract referencing the token being used for voting.
IVotesUpgradeable private votingToken;

/// @notice Thrown if the voting power is zero
Expand All @@ -42,7 +42,8 @@ contract TokenVoting is IMembership, MajorityVotingBase {
/// @param _votingSettings The voting settings.
/// @param _token The [ERC-20](https://eips.ethereum.org/EIPS/eip-20) token used for voting.
/// @param _minApprovals The minimal amount of approvals the proposal needs to succeed.
function initialize(
/// @param _pluginMetadata The plugin specific information encoded in bytes.
function initialize(
IDAO _dao,
VotingSettings calldata _votingSettings,
IVotesUpgradeable _token,
Expand All @@ -63,7 +64,7 @@ contract TokenVoting is IMembership, MajorityVotingBase {
emit MembershipContractAnnounced({definingContract: address(_token)});
}

/// @notice Reinitializes the TokenVoting after an upgrade from a previous protocol version. For each
/// @notice Reinitializes the TokenVoting after an upgrade from a previous build version. For each
/// reinitialization step, use the `_fromBuild` version to decide which internal functions to
/// call for reinitialization.
/// @dev WARNING: The contract should only be upgradeable through PSP to ensure that _fromBuild is not
Expand Down Expand Up @@ -99,7 +100,7 @@ contract TokenVoting is IMembership, MajorityVotingBase {

/// @notice getter function for the voting token.
/// @dev public function also useful for registering interfaceId
/// and for distinguishing from majority voting interface.
/// and for distinguishing from majority voting interface.
/// @return The token used for voting.
function getVotingToken() public view returns (IVotesUpgradeable) {
return votingToken;
Expand All @@ -111,6 +112,7 @@ contract TokenVoting is IMembership, MajorityVotingBase {
}

/// @inheritdoc MajorityVotingBase
/// @dev Requires the `CREATE_PROPOSAL_PERMISSION_ID` permission.
function createProposal(
bytes calldata _metadata,
Action[] calldata _actions,
Expand Down
6 changes: 3 additions & 3 deletions packages/contracts/src/TokenVotingSetup.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,8 +70,8 @@ contract TokenVotingSetup is PluginUpgradeableSetup {

/// @notice Configuration settings for a token used within the governance system.
/// @param addr The token address. If set to `address(0)`, a new `GovernanceERC20` token is deployed.
/// If the address implements `IVotes`, it will be used directly; otherwise,
/// it is wrapped as `GovernanceWrappedERC20`.
/// If the address implements `IVotes`, it will be used directly; otherwise,
/// it is wrapped as `GovernanceWrappedERC20`.
/// @param name The name of the token, relevant only if a new token is deployed (i.e., `addr` is `address(0)`).
/// @param symbol The symbol of the token, relevant only if a new token is deployed (i.e., `addr` is `address(0)`).
struct TokenSettings {
Expand All @@ -89,7 +89,7 @@ contract TokenVotingSetup is PluginUpgradeableSetup {
error TokenNotERC20(address token);

/// @notice The contract constructor deploying the plugin implementation contract
/// and receiving the governance token base contracts to clone from.
/// and receiving the governance token base contracts to clone from.
/// @param _governanceERC20Base The base `GovernanceERC20` contract to create clones from.
/// @param _governanceWrappedERC20Base The base `GovernanceWrappedERC20` contract to create clones from.
constructor(
Expand Down
2 changes: 1 addition & 1 deletion packages/contracts/src/VotingPowerCondition.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ import {PermissionCondition} from "@aragon/osx-commons-contracts/src/permission/

/// @title VotingPowerCondition
/// @notice Checks if an account's voting power or token balance meets the threshold set
/// in an associated TokenVoting plugin.
/// in an associated TokenVoting plugin.
/// @author Aragon X - 2024
/// @custom:security-contact [email protected]
contract VotingPowerCondition is PermissionCondition {
Expand Down

0 comments on commit 8d1dce9

Please sign in to comment.