docs(protocol): cleanup protocol docs (taikoxyz#14462)

CONTRIBUTING.md

@@ -33,9 +33,9 @@ For example, `feat(scope): description of feature` should only impact the `scope
 
 Follow the [NatSpec format](https://docs.soliditylang.org/en/latest/natspec-format.html) for documenting smart contract source code. Please adhere to a few additional standards:
 
-#### Multi-line comments
+#### Comment style
 
-Choose `/** */` over `///` for multi-line NatSpec comments to save column space.
+Choose `///` over `/** */` for multi-line NatSpec comments for consistency. All NatSpec comments should use `///` instead of `/** */`. Additional explanatory comments should use `//`, even for multi-line comments.
 
 #### Notice tag
 
@@ -152,6 +152,64 @@ struct Some {
 }
 ```
 
+#### Mentioning other files in the repo
+
+To mention another contract file in the repo use the standard like this:
+
+```solidity
+/// @notice See the documentation in {IProverPool}
+```
+
+If you are referring to some struct or function within the file you can use the standard like this:
+
+```solidity
+/// @notice See the struct in {TaikoData.Config}
+```
+
+#### Documenting interfaces
+
+To document the implementing contract of an interface, you cannot use `@inheritdoc`, it is not supported for contracts. Thus, you should mention a statement like so:
+
+```solidity
+/// @notice See the documentation in {IProverPool}
+```
+
+You can then mention implementation specific details by adding a `@dev` tag:
+
+```solidity
+/// @notice See the documentation in {IProverPool}
+/// @dev This implementation uses a ProverPool of size 32.
+```
+
+#### Documenting internal functions and structs
+
+Internal functions and structs should commented with a `@dev` tag, and you can also comment the contents of the struct with explanatory comments.
+
+#### Documenting user-facing functions versus internal functions
+
+All user-facing functions should be fully documented with NatSpec. Internal functions should always be commented with a `@dev` tag, not a `@notice` tag.
+
+#### Explanatory comments
+
+Explanatory comments use `//`. There is a common idea that the code describes the documentation. There are pros to this approach. One of the pros is that you remove the coupling between documentation and the code it's describing, that's why we should always strive for the [minimum viable documentation](https://google.github.io/styleguide/docguide/best_practices.html#minimum-viable-documentation) (one of our core documentation [philosophies](#philosophies)). It can also appear cleaner.
+
+It's important that our codebase is well documented with **explanatory comments**. Thus, in addition to the standard NatSpec documentation which we should apply, we should comment the more complex things in our codebase for higher readability. More important than commenting _what_ we should be concerned with commenting _why_. The _what_ does not need to be commented for obvious things, of course the code is able to achieve that. We should comment the _what_ for more complex things to aid in the reader for more quickly understanding the code. In addition to that, we should strive to answer the _why_ with comments in our code.
+
+Keep in mind the advantage of having minimum viable documentation. Keep the comments close to the code which it is describing, so that it does not easily go stale or out of date.
+
+#### Annotation ordering
+
+There are several annotations used in NatSpec, this is the order of precedence we use from top to bottom:
+
+- @title
+- @author [we don't use this tag]
+- @notice
+- @dev
+- @param
+- @return
+- @inheritdoc
+- @custom [we don't use this tag unless we define the convention for it here]
+
 ## Documentation standards
 
 This section describes our documentation standards at Taiko.

packages/protocol/contracts/L1/IProofVerifier.sol

@@ -6,20 +6,15 @@
 
 pragma solidity ^0.8.20;
 
-/**
- * @title IProofVerifier Interface
- * @dev Interface for the ProofVerifier contract which is responsible for
- * verifying proofs.
- */
+/// @title IProofVerifier
+/// @notice Contract that is responsible for verifying proofs.
 interface IProofVerifier {
-    /**
-     * @notice Verify proof(s) for the given block.
-     * This function should revert if the verification fails.
-     *
-     * @param blockId Unique identifier for the block.
-     * @param blockProofs Raw bytes representing the proof(s).
-     * @param instance Hash combining evidence and configuration data.
-     */
+    /// @notice Verify the given proof(s) for the given blockId. This function
+    /// should revert if the verification fails.
+    /// @param blockId Unique identifier for the block.
+    /// @param blockProofs Raw bytes representing the proof(s).
+    /// @param instance Hashed evidence & config data. If set to zero, proof is
+    /// assumed to be from oracle/system prover.
     function verifyProofs(
         uint256 blockId,
         bytes calldata blockProofs,

packages/protocol/contracts/L1/IProverPool.sol

@@ -6,42 +6,32 @@
 
 pragma solidity ^0.8.20;
 
-/**
- * @title IProverPool Interface
- * @dev Interface for the ProverPool contract, which manages the assignment,
- * release, and slashing of provers.
- */
+/// @title IProverPool
+/// @notice Interface which manages the assignment, release, and slashing of
+/// provers. This pool is where the protocol selects provers from to prove L1
+/// block validity.
 interface IProverPool {
-    /**
-     * @notice Assigns a prover to a specific block.
-     *
-     * @param blockId Unique identifier for the block.
-     * @param feePerGas The fee amount per unit of gas.
-     * @return prover Address of the assigned prover.
-     * @return rewardPerGas Reward allocated per unit of gas for the prover.
-     */
+    /// @notice Assigns a prover to a specific block.
+    /// @param blockId Unique identifier for the block.
+    /// @param feePerGas The fee amount per unit of gas.
+    /// @return prover Address of the assigned prover.
+    /// @return rewardPerGas Reward allocated per unit of gas for the prover.
     function assignProver(
         uint64 blockId,
         uint32 feePerGas
     )
         external
         returns (address prover, uint32 rewardPerGas);
 
-    /**
-     * @notice Releases a prover.
-     *
-     * @param prover Address of the prover to be released.
-     */
+    /// @notice Releases a prover.
+    /// @param prover Address of the prover to be released.
     function releaseProver(address prover) external;
 
-    /**
-     * @notice Penalizes a prover by burning their staked tokens.
-     *
-     * @param blockId Unique identifier for the block associated with the
-     * prover's task.
-     * @param prover Address of the prover being penalized.
-     * @param proofReward Reward initially allocated for proof validation.
-     */
+    /// @notice Penalizes a prover by burning their staked tokens.
+    /// @param blockId Unique identifier for the block associated with the
+    /// prover's task.
+    /// @param prover Address of the prover being penalized.
+    /// @param proofReward Reward initially allocated for proof validation.
     function slashProver(
         uint64 blockId,
         address prover,

packages/protocol/contracts/L1/ProofVerifier.sol

@@ -13,33 +13,24 @@ import { LibZKPVerifier } from "./libs/verifiers/LibZKPVerifier.sol";
 import { IProofVerifier } from "./IProofVerifier.sol";
 import { LibBytesUtils } from "../thirdparty/LibBytesUtils.sol";
 
-/**
- * @title ProofVerifier
- * @dev Contract for verifying proofs in the rollup.
- */
+/// @title ProofVerifier
+/// @notice See the documentation in {IProofVerifier}.
 contract ProofVerifier is EssentialContract, IProofVerifier {
     uint256[50] private __gap;
 
     error L1_INVALID_PROOF();
 
-    /**
-     * @notice Initializes the contract with the provided address manager.
-     * @param _addressManager The address of the address manager contract.
-     */
+    /// @notice Initializes the contract with the provided address manager.
+    /// @param _addressManager The address of the address manager contract.
     function init(address _addressManager) external initializer {
         EssentialContract._init(_addressManager);
     }
 
-    /**
-     * @notice Verifies the provided proofs.
-     * @dev Throws an error if verification fails.
-     *
-     * @param blockProofs Raw bytes of proof(s).
-     * @param instance Hashed evidence & config data. If set to zero, proof is
-     * assumed to be from oracle/system prover.
-     */
+    /// @inheritdoc IProofVerifier
     function verifyProofs(
-        uint256, /*blockId*/
+        // blockId is unused now, but can be used later when supporting
+        // different types of proofs.
+        uint256,
         bytes calldata blockProofs,
         bytes32 instance
     )
@@ -79,8 +70,6 @@ contract ProofVerifier is EssentialContract, IProofVerifier {
     }
 }
 
-/**
- * @title ProxiedProofVerifier
- * @dev Proxied version of the ProofVerifier contract.
- */
+/// @title ProxiedProofVerifier
+/// @notice Proxied version of the ProofVerifier contract.
 contract ProxiedProofVerifier is Proxied, ProofVerifier { }