comments and linting

contracts/IPAccountImpl.sol

@@ -185,5 +185,4 @@ contract IPAccountImpl is IERC165, IIPAccount {
             }
         }
     }
-
 }

contracts/governance/Governable.sol

@@ -7,6 +7,7 @@ import { IGovernance } from "contracts/interfaces/governance/IGovernance.sol";
 import { IGovernable } from "../interfaces/governance/IGovernable.sol";
 import { ERC165Checker } from "@openzeppelin/contracts/utils/introspection/ERC165Checker.sol";
 import { GovernanceLib } from "contracts/lib/GovernanceLib.sol";
+
 /// @title Governable
 /// @dev All contracts managed by governance should inherit from this contract.
 abstract contract Governable is IGovernable {
@@ -15,7 +16,7 @@ abstract contract Governable is IGovernable {
 
     /// @dev Ensures that the function is called by the protocol admin.
     modifier onlyProtocolAdmin() {
-        if(!IGovernance(governance).hasRole(GovernanceLib.PROTOCOL_ADMIN, msg.sender)) {
+        if (!IGovernance(governance).hasRole(GovernanceLib.PROTOCOL_ADMIN, msg.sender)) {
             revert Errors.Governance__OnlyProtocolAdmin();
         }
         _;

contracts/interfaces/licensing/ILinkParamVerifier.sol

@@ -4,6 +4,9 @@ pragma solidity ^0.8.23;
 
 import { IParamVerifier } from "contracts/interfaces/licensing/IParamVerifier.sol";
 
+/// @title ILinkParamVerifier
+/// @notice LicenseRegistry will call this to verify the linking an IP to its parent
+/// with the policy referenced by the license in use.
 interface ILinkParamVerifier is IParamVerifier {
     function verifyLink(
         uint256 licenseId,

contracts/interfaces/licensing/IMintParamVerifier.sol

@@ -3,10 +3,13 @@
 pragma solidity ^0.8.23;
 import { IParamVerifier } from "contracts/interfaces/licensing/IParamVerifier.sol";
 
+/// @title IMintParamVerifier
+/// @notice LicenseRegistry will call this to verify the minting parameters are compliant
+/// with the policy associated with the license to mint.
 interface IMintParamVerifier is IParamVerifier {
     function verifyMint(
         address caller,
-        bool policyAddedByLinking,
+        bool policyWasInherited,
         address licensors,
         address receiver,
         uint256 mintAmount,

contracts/interfaces/licensing/IParamVerifier.sol

@@ -4,6 +4,8 @@ pragma solidity ^0.8.23;
 
 import { IERC165 } from "@openzeppelin/contracts/interfaces/IERC165.sol";
 
+/// @title IParamVerifier
+/// @notice Placeholder interface for verifying policy parameters.
 interface IParamVerifier is IERC165 {
 
 }

contracts/interfaces/licensing/ITransferParamVerifier.sol

@@ -4,12 +4,15 @@ pragma solidity ^0.8.23;
 
 import { IParamVerifier } from "contracts/interfaces/licensing/IParamVerifier.sol";
 
+/// @title ITransferParamVerifier
+/// @notice LicenseRegistry will call this to verify the transfer parameters are compliant
+/// with the policy
 interface ITransferParamVerifier is IParamVerifier {
     function verifyTransfer(
         uint256 licenseId,
         address from,
         address to,
         uint256 amount,
-        bytes memory data
+        bytes memory policyData
     ) external returns (bool);
 }

contracts/interfaces/licensing/IUMLPolicyFrameworkManager.sol

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: UNLICENSED
+
+pragma solidity ^0.8.23;
+
+import { Licensing } from "contracts/lib/Licensing.sol";
+import { IPolicyFrameworkManager } from "contracts/interfaces/licensing/IPolicyFrameworkManager.sol";
+
+/// @notice Licensing parameters for the UML standard
+/// @param attribution Whether or not attribution is required when reproducing the work
+/// @param transferable Whether or not the license is transferable
+/// @param commercialUse Whether or not the work can be used commercially
+/// @param commercialAttribution Whether or not attribution is required when reproducing the work commercially
+/// @param commercializers List of commericializers that are allowed to commercially exploit the work. If empty
+/// then no restrictions.
+/// @param commercialRevShare Percentage of revenue that must be shared with the licensor
+/// @param derivativesAllowed Whether or not the licensee can create derivatives of his work
+/// @param derivativesAttribution Whether or not attribution is required for derivatives of the work
+/// @param derivativesApproval Whether or not the licensor must approve derivatives of the work before they can be
+/// linked to the licensor IP ID
+/// @param derivativesReciprocal Whether or not the licensee must license derivatives of the work under the same terms.
+/// @param derivativesRevShare Percentage of revenue that must be shared with the licensor for derivatives of the work
+/// @param territories List of territories where the license is valid. If empty, global.
+/// @param distributionChannels List of distribution channels where the license is valid. Empty if no restrictions.
+struct UMLPolicy {
+    bool attribution;
+    bool transferable;
+    bool commercialUse;
+    bool commercialAttribution;
+    string[] commercializers;
+    uint256 commercialRevShare;
+    bool derivativesAllowed;
+    bool derivativesAttribution;
+    bool derivativesApproval;
+    bool derivativesReciprocal;
+    uint256 derivativesRevShare;
+    string[] territories;
+    string[] distributionChannels;
+}
+
+
+/// @title IUMLPolicyFrameworkManager
+/// @notice Defines the interface for a Policy Framework Manager compliant with the UML standard
+interface IUMLPolicyFrameworkManager is IPolicyFrameworkManager {
+
+    /// @notice Emitted when a new policy is added to the registry
+    event UMLPolicyAdded(uint256 indexed policyId, UMLPolicy policy);
+
+    /// @notice Adds a new policy to the registry
+    /// @dev Must encode the policy into bytes to be stored in the LicenseRegistry
+    /// @param umlPolicy UMLPolicy compliant licensing term values
+    function addPolicy(UMLPolicy calldata umlPolicy) external returns (uint256 policyId);
+    /// @notice Fetchs a policy from the registry, decoding the raw bytes into a UMLPolicy struct
+    /// @param policyId  The ID of the policy to fetch
+    /// @return policy The UMLPolicy struct
+    function getPolicy(uint256 policyId) external view returns (UMLPolicy memory policy);
+}

contracts/interfaces/registries/ILicenseRegistry.sol

@@ -3,15 +3,39 @@ pragma solidity ^0.8.23;
 
 import { Licensing } from "contracts/lib/Licensing.sol";
 
+/// @title ILicenseRegistry
+/// @notice Interface for the LicenseRegistry contract, which is the main entry point for the licensing system.
+/// It is responsible for:
+/// - Registering policy frameworks
+/// - Registering policies
+/// - Minting licenses
+/// - Linking IP to its parent
+/// - Verifying transfer parameters (through the ITransferParamVerifier interface implementation by the policy framework)
+/// - Verifying linking parameters (through the ILinkParamVerifier interface implementation by the policy framework)
+/// - Verifying policy parameters (through the IParamVerifier interface implementation by the policy framework)
 interface ILicenseRegistry {
+
+    /// @notice Emitted when a policy framework is created by registering a policy framework manager
+    /// @param creator The address that created the policy framework
+    /// @param frameworkId The id of the policy framework
+    /// @param framework The policy framework data
     event PolicyFrameworkCreated(
         address indexed creator,
         uint256 indexed frameworkId,
         Licensing.PolicyFramework framework
     );
-
+    /// @notice Emitted when a policy is added to the contract.
+    /// @param creator The address that created the policy
+    /// @param policyId The id of the policy
+    /// @param policy The policy data
     event PolicyCreated(address indexed creator, uint256 indexed policyId, Licensing.Policy policy);
 
+    /// @notice Emitted when a policy is added to an IP
+    /// @param caller The address that called the function
+    /// @param ipId The id of the IP
+    /// @param policyId The id of the policy
+    /// @param index The index of the policy in the IP's policy list
+    /// @param inheritedPolicy Whether the policy was inherited from a parent IP (linking) or set by IP owner
     event PolicyAddedToIpId(
         address indexed caller,
         address indexed ipId,
@@ -20,6 +44,12 @@ interface ILicenseRegistry {
         bool inheritedPolicy
     );
 
+    /// @notice Emitted when a license is minted
+    /// @param creator The address that created the license
+    /// @param receiver The address that received the license
+    /// @param licenseId The id of the license
+    /// @param amount The amount of licenses minted
+    /// @param licenseData The license data
     event LicenseMinted(
         address indexed creator,
         address indexed receiver,
@@ -28,59 +58,87 @@ interface ILicenseRegistry {
         Licensing.License licenseData
     );
 
+    /// @notice Emitted when an IP is linked to its parent by burning a license
+    /// @param caller The address that called the function
+    /// @param ipId The id of the IP
+    /// @param parentIpId The id of the parent IP
     event IpIdLinkedToParent(address indexed caller, address indexed ipId, address indexed parentIpId);
 
+    /// @notice registers a policy framework into the contract
+    /// @param fw The policy framework data
+    /// @return frameworkId The id of the policy framework 
     function addPolicyFramework(Licensing.PolicyFramework calldata fw) external returns (uint256 frameworkId);
 
-    function addPolicyToIp(address ipId, uint256 polId) external returns (uint256 indexOnIpId);
-
+    /// @notice registers a policy into the contract
+    /// @param pol The policy data
+    /// @return policyId The id of the policy
     function addPolicy(Licensing.Policy memory pol) external returns (uint256 policyId);
 
+    /// @notice adds a policy to an IP policy list
+    /// @param ipId The id of the IP
+    /// @param polId The id of the policy
+    /// @return indexOnIpId The index of the policy in the IP's policy list
+    function addPolicyToIp(address ipId, uint256 polId) external returns (uint256 indexOnIpId);
+
+    /// @notice mints a license to create derivative IP
+    /// @param policyId The id of the policy with the licensing parameters
+    /// @param licensorIpId The id of the licensor IP
+    /// @param amount The amount of licenses to mint
+    /// @param receiver The address that will receive the license
     function mintLicense(
         uint256 policyId,
         address licensorIpId,
         uint256 amount,
         address receiver
     ) external returns (uint256 licenseId);
 
+    /// @notice links an IP to its parent IP, burning the license NFT and the policy allows it
+    /// @param licenseId The id of the license to burn
+    /// @param childIpId The id of the child IP
+    /// @param holder The address that holds the license
     function linkIpToParent(uint256 licenseId, address childIpId, address holder) external;
 
     ///
     /// Getters
     ///
 
+    /// @notice gets total number of policy frameworks in the contract
     function totalFrameworks() external view returns (uint256);
-
+    /// @notice gets policy framework data by id
     function framework(uint256 frameworkId) external view returns (Licensing.PolicyFramework memory);
+    /// @notice gets policy framework license template URL by id
     function frameworkUrl(uint256 frameworkId) external view returns (string memory);
-
+    /// @notice gets total number of policies (framework parameter configurations) in the contract
     function totalPolicies() external view returns (uint256);
-
+    /// @notice gets policy data by id
     function policy(uint256 policyId) external view returns (Licensing.Policy memory pol);
-
+    /// @notice true if policy is defined in the contract
     function isPolicyDefined(uint256 policyId) external view returns (bool);
-
+    /// @notice gets the policy ids for an IP
     function policyIdsForIp(address ipId) external view returns (uint256[] memory policyIds);
-
+    /// @notice gets total number of policies for an IP
     function totalPoliciesForIp(address ipId) external view returns (uint256);
-
+    /// @notice true if policy is part of an IP's policy list
     function isPolicyIdSetForIp(address ipId, uint256 policyId) external view returns (bool);
-
+    /// @notice gets the policy ID for an IP by index on the IP's policy list
     function policyIdForIpAtIndex(address ipId, uint256 index) external view returns (uint256 policyId);
-
+    /// @notice gets the policy for an IP by index on the IP's policy list
     function policyForIpAtIndex(address ipId, uint256 index) external view returns (Licensing.Policy memory);
-
+    /// @notice gets the index of a policy in an IP's policy list
     function indexOfPolicyForIp(address ipId, uint256 policyId) external view returns (uint256 index);
-
+    /// @notice true if the license was added to the IP by linking (burning a license)
     function isPolicyInherited(address ipId, uint256 policyId) external view returns (bool);
-
+    /// @notice true if holder is the licensee for the license (owner of the license NFT), or derivative IP owner if
+    /// the license was added to the IP by linking (burning a license)
     function isLicensee(uint256 licenseId, address holder) external view returns (bool);
-
+    /// @notice IP ID of the licensor for the license (parent IP)
     function licensorIpId(uint256 licenseId) external view returns (address);
+    /// @notice license data (licensor, policy...) for the license id
     function license(uint256 licenseId) external view returns (Licensing.License memory);
+    /// @notice true if an IP is a derivative of another IP
     function isParent(address parentIpId, address childIpId) external view returns (bool);
-
+    /// @notice returns the parent IP IDs for an IP ID
     function parentIpIds(address ipId) external view returns (address[] memory);
-
+    /// @notice total number of parents for an IP ID
     function totalParentsForIpId(address ipId) external view returns (uint256);
 }

contracts/lib/Errors.sol

@@ -22,7 +22,6 @@ library Errors {
     error IPAccount__InvalidSignature();
     error IPAccount__ExpiredSignature();
 
-
     ////////////////////////////////////////////////////////////////////////////
     //                                   Module                               //
     ////////////////////////////////////////////////////////////////////////////
@@ -70,7 +69,6 @@ library Errors {
     //                            LicenseRegistry                             //
     ////////////////////////////////////////////////////////////////////////////
 
-    /// @notice Error thrown when a policy is already set for an IP ID.
     error LicenseRegistry__PolicyAlreadySetForIpId();
     error LicenseRegistry__FrameworkNotFound();
     error LicenseRegistry__EmptyLicenseUrl();
@@ -109,7 +107,7 @@ library Errors {
     error UMLPolicyFrameworkManager_DerivativesDisabled_CantAddReciprocal();
     error UMLPolicyFrameworkManager_DerivativesDisabled_CantAddRevShare();
     error UMLPolicyFrameworkManager_FrameworkNotYetRegistered();
-    
+
     ////////////////////////////////////////////////////////////////////////////
     //                     LicensorApprovalManager                            //
     ////////////////////////////////////////////////////////////////////////////

contracts/lib/GovernanceLib.sol

@@ -5,12 +5,11 @@ pragma solidity ^0.8.23;
 /// @title Governance
 /// @dev This library provides types for Story Protocol Governance.
 library GovernanceLib {
-
     bytes32 public constant PROTOCOL_ADMIN = bytes32(0);
 
-     /// @notice An enum containing the different states the protocol can be in.
-     /// @param Unpaused The unpaused state.
-     /// @param Paused The paused state.
+    /// @notice An enum containing the different states the protocol can be in.
+    /// @param Unpaused The unpaused state.
+    /// @param Paused The paused state.
     enum ProtocolState {
         Unpaused,
         Paused

contracts/lib/Licensing.sol

@@ -4,32 +4,35 @@ pragma solidity ^0.8.20;
 import { IParamVerifier } from "../interfaces/licensing/IParamVerifier.sol";
 import { Errors } from "./Errors.sol";
 
+/// @title Licensing
+/// @notice Types and constants used by the licensing related contracts
 library Licensing {
-
-    /// Describes a licensing framework, which is a set of licensing terms (parameters)
+    /// @notice Describes a license policy framework, which is a set of licensing terms (parameters)
     /// that come into effect in different moments of the licensing life cycle.
     /// Must correspond to human (or at least lawyer) readable text describing them in licenseUrl.
-    /// To be valid in Story Protocol, the parameters described in the text must express default values
-    /// corresponding to those of each Parameter struct
+    /// To be valid in Story Protocol, the policy framework must be registered in the LicenseRegistry.
+    /// @param policyFramework Address of the contract implementing the policy framework encoding and logic
+    /// @param licenseUrl URL to the file containing the legal text for the license agreement
     struct PolicyFramework {
         address policyFramework;
-        /// @notice URL to the file containing the legal text for the license agreement
         string licenseUrl;
     }
 
-    /// A particular configuration of a Licensing PolicyFramework, setting (or not) values for the licensing
+    /// @notice A particular configuration (flavor) of a Policy Framework, setting values for the licensing
     /// terms (parameters) of the framework.
+    /// @param policyFrameworkId Id of the policy framework this policy is based on
+    /// @param policyData Encoded data for the policy, specific to the policy framework
     struct Policy {
-        /// Id of a Licensing PolicyFramework
         uint256 frameworkId;
         bytes data;
     }
 
-    /// Data that define a License Agreement NFT
+    /// @notice Data that define a License Agreement NFT
+    /// @param policyId Id of the policy this license is based on, which will be set in the derivative
+    /// IP when the license is burnt
+    /// @param licensorIpId Id of the IP this license is for
     struct License {
-        /// the id for the Policy this License will set to the desired derivative IP after being burned.
         uint256 policyId;
-        /// Id for the licensor of the Ip Id
         address licensorIpId;
     }
-}
+}