docs: improved NatSpec

aragon · Sep 26, 2023 · d52c496 · d52c496
1 parent 460b31e
commit d52c496
Show file tree

Hide file tree

Showing 3 changed files with 6 additions and 5 deletions.
diff --git 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
@@ -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 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
@@ -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 {