misc: Natspec and TODOs added for Reference and PubActions modules

contracts/interfaces/IPublicationActionModule.sol

@@ -9,18 +9,27 @@ import {Types} from 'contracts/libraries/constants/Types.sol';
  * @author Lens Protocol
  *
  * @notice This is the standard interface for all Lens-compatible Publication Actions.
+ * Publication action modules allow users to execute actions directly from a publication, like:
+ *  - Minting NFTs
+ *  - Collecting a publication
+ *  - Sending funds to the profile owner (tipping, etc)
+ *  - etc
+ * Referrers are supported, so any publication or profile that references the publication can receive a share from the
+ * publication's action if the action module supports it.
  */
 interface IPublicationActionModule {
     /**
-     * @notice Initializes the action module for the given publication.
+     * @notice Initializes the action module for the given publication being published with this Action module.
      * @custom:permissions LensHub.
      *
-     * @param profileId The profile ID of the author publishing the content with Publication Action.
-     * @param pubId The publication ID of the content being published.
+     * @param profileId The profile ID of the author publishing the content with this Publication Action.
+     * @param pubId The publication ID being published.
      * @param transactionExecutor The address of the transaction executor (e.g. for any funds to transferFrom).
-     * @param data The data to be passed to the Publication Action.
+     * @param data Arbitrary data passed from the user to be decoded by the Action Module during initialization.
      *
-     * @return bytes Any custom ABI-encoded data depending on the module implementation.
+     * @return bytes An abi-encoded byte array encapsulating the execution's state changes. This will be emitted by the
+     * hub alongside the collect module's address and should be consumed by front ends.
+     * // TODO: Is the above return description correct?
      */
     function initializePublicationAction(
         uint256 profileId,
@@ -31,11 +40,12 @@ interface IPublicationActionModule {
 
     /**
      * @notice Initializes the action module for the given publication.
-     * @custom:permissions LensHub.
+     * @custom:permissions LensHub
      *
      * @param processActionParams The parameters needed to execute the publication action.
      *
      * @return bytes Any custom ABI-encoded data depending on the module implementation.
+     * // TODO: Do we need to return data? Reference modules do not return anything.
      */
     function processPublicationAction(
         Types.ProcessActionParams calldata processActionParams

contracts/interfaces/IReferenceModule.sol

@@ -9,15 +9,20 @@ import {Types} from 'contracts/libraries/constants/Types.sol';
  * @author Lens Protocol
  *
  * @notice This is the standard interface for all Lens-compatible ReferenceModules.
+ * Reference modules allow executing some action when a publication is referenced, like:
+ *  - rewards for mirroring/commenting/quoting a publication
+ *  - token-gated comments/mirrors/quotes of a publication
+ *  - etc
  */
 interface IReferenceModule {
     /**
-     * @notice Initializes data for a given publication being published. This can only be called by the hub.
+     * @notice Initializes data for the given publication being published with this Reference module.
+     * @custom:permissions LensHub
      *
      * @param profileId The token ID of the profile publishing the publication.
-     * @param transactionExecutor The owner or an approved delegated executor.
+     * @param transactionExecutor The address of the transaction executor (e.g. for any funds to transferFrom).
      * @param pubId The associated publication's LensHub publication ID.
-     * @param data Arbitrary data passed from the user to be decoded.
+     * @param data Arbitrary data passed from the user to be decoded by the Reference Module during initialization.
      *
      * @return bytes An abi-encoded byte array encapsulating the execution's state changes. This will be emitted by the
      * hub alongside the collect module's address and should be consumed by front ends.
@@ -25,13 +30,34 @@ interface IReferenceModule {
     function initializeReferenceModule(
         uint256 profileId,
         address transactionExecutor,
-        uint256 pubId,
+        uint256 pubId, // TODO: Move this near profileId
         bytes calldata data
     ) external returns (bytes memory);
 
+    /**
+     * @notice Processes a comment being published. This includes any additional module logic like transferring tokens,
+     * checking for conditions (e.g. token-gated), etc.
+     * @custom:permissions LensHub
+     *
+     * @param processCommentParams The parameters for processing a comment.
+     */
     function processComment(Types.ProcessCommentParams calldata processCommentParams) external;
 
+    /**
+     * @notice Processes a quote being published. This includes any additional module logic like transferring tokens,
+     * checking for conditions (e.g. token-gated), etc.
+     * @custom:permissions LensHub
+     *
+     * @param processQuoteParams The parameters for processing a quote.
+     */
     function processQuote(Types.ProcessQuoteParams calldata processQuoteParams) external;
 
+    /**
+     * @notice Processes a mirror being published. This includes any additional module logic like transferring tokens,
+     * checking for conditions (e.g. token-gated), etc.
+     * @custom:permissions LensHub
+     *
+     * @param processMirrorParams The parameters for processing a mirror.
+     */
     function processMirror(Types.ProcessMirrorParams calldata processMirrorParams) external;
 }