From 760174e55752241c47769c3161b8651d650fc391 Mon Sep 17 00:00:00 2001 From: Michael Heuer Date: Tue, 26 Sep 2023 17:53:26 +0200 Subject: [PATCH] docs: improved NatSpec --- .../contracts/src/framework/plugin/repo/PluginRepo.sol | 2 +- packages/contracts/src/utils/protocol/IProtocolVersion.sol | 7 ++++--- packages/contracts/src/utils/protocol/ProtocolVersion.sol | 2 +- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/packages/contracts/src/framework/plugin/repo/PluginRepo.sol b/packages/contracts/src/framework/plugin/repo/PluginRepo.sol index 95b0c7466..80dbc5e74 100644 --- a/packages/contracts/src/framework/plugin/repo/PluginRepo.sol +++ b/packages/contracts/src/framework/plugin/repo/PluginRepo.sol @@ -33,7 +33,7 @@ contract PluginRepo is /// @notice The struct describing the tag of a version obtained by a release and build number as `RELEASE.BUILD`. /// @param release The release number. /// @param build The build number - /// @dev Releases can include a storage layout or the addition of new functions. Builds include logic changes or updates of the UI. + /// @dev Releases mark incompatible changes (e.g., the plugin interface, storage layout, or incompatible behavior) whereas builds mark compatible changes (e.g., patches and compatible feature additions). struct Tag { uint8 release; uint16 build; diff --git a/packages/contracts/src/utils/protocol/IProtocolVersion.sol b/packages/contracts/src/utils/protocol/IProtocolVersion.sol index e9ba44c8c..79cdde4cc 100644 --- a/packages/contracts/src/utils/protocol/IProtocolVersion.sol +++ b/packages/contracts/src/utils/protocol/IProtocolVersion.sol @@ -4,10 +4,11 @@ pragma solidity ^0.8.8; /// @title IProtocolVersion /// @author Aragon Association - 2022-2023 -/// @notice An interface defining the semantic OSx protocol version. +/// @notice An interface defining the semantic Aragon OSx protocol version number. /// @custom:security-contact sirt@aragon.org interface IProtocolVersion { - /// @notice Returns the protocol version at which the current contract was built. Use it to check for future upgrades that might be applicable. - /// @return _version Returns the semantic OSx protocol version. + /// @notice Returns the semantic Aragon OSx protocol version number that the implementing contract is associated with. + /// @return _version Returns the semantic Aragon OSx protocol version number. + /// @dev This version number is not to be confused with the `release` and `build` numbers found in the `Version.Tag` struct inside the `PluginRepo` contract being used to version plugin setup and associated plugin implementation contracts. function protocolVersion() external view returns (uint8[3] memory _version); } diff --git a/packages/contracts/src/utils/protocol/ProtocolVersion.sol b/packages/contracts/src/utils/protocol/ProtocolVersion.sol index f9ef337fb..7a59c24f1 100644 --- a/packages/contracts/src/utils/protocol/ProtocolVersion.sol +++ b/packages/contracts/src/utils/protocol/ProtocolVersion.sol @@ -6,7 +6,7 @@ import {IProtocolVersion} from "./IProtocolVersion.sol"; /// @title ProtocolVersion /// @author Aragon Association - 2023 -/// @notice An abstract, stateless, non-upgradeable contract serves as a base for other contracts requiring awareness of the OSx protocol version. +/// @notice An abstract, stateless, non-upgradeable contract serving as a base for other contracts requiring awareness of the OSx protocol version. /// @dev Do not add any new variables to this contract that would shift down storage in the inheritance chain. /// @custom:security-contact sirt@aragon.org abstract contract ProtocolVersion is IProtocolVersion {