docs(protocol,repo): standardize protocol docs (taikoxyz#16178)

Co-authored-by: David <[email protected]>

CONTRIBUTING.md

@@ -29,26 +29,53 @@ Because we squash all of the changes into a single commit, please try to keep th
 
 For example, `feat(scope): description of feature` should only impact the `scope` package. If your change is a global one, you can use `feat: description of feature`, for example.
 
-### Source code comments
+### Source code comments (NatSpec)
 
 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:
 
+#### Contract header
+
+All contracts should have at the top, and nothing else (minimum viable documentation):
+
+```
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.24;
+```
+
+All contracts should have, preceding their declaration, at minimum:
+
+```
+/// @title A title
+/// @custom:security-contact [email protected]
+```
+
+#### Single tag
+
+Always use a single tag, for example do not do this:
+
+```
+/// @dev Here is a dev comment.
+/// @dev Here is another dev comment.
+```
+
+Instead, combine them into a single comment.
+
 #### Comment style
 
 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
 
-Omit the usage of `@notice` and let the compiler automatically pick it up to save column space. For example, this:
+Explicitly use `@notice`, don't let the compiler pick it up automatically:
 
 ```
-/// @notice This is a notice.
+/// This is a notice.
 ```
 
 becomes this:
 
 ```
-/// This is a notice.
+/// @notice This is a notice.
 ```
 
 #### Annotation indentation
@@ -168,7 +195,7 @@ If you are referring to some struct or function within the file you can use the
 
 #### 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:
+To document the implementing contract of an interface, you cannot use `@inheritdoc`, it is not supported for contracts at the top-level. Thus, you should mention a statement like so:
 
 ```solidity
 /// @notice See the documentation in {IProverPool}

packages/protocol/contracts/L1/ITaikoL1.sol

@@ -1,17 +1,4 @@
 // SPDX-License-Identifier: MIT
-//  _____     _ _         _         _
-// |_   _|_ _(_) |_____  | |   __ _| |__ ___
-//   | |/ _` | | / / _ \ | |__/ _` | '_ (_-<
-//   |_|\__,_|_|_\_\___/ |____\__,_|_.__/__/
-//
-//   Email: [email protected]
-//   Website: https://taiko.xyz
-//   GitHub: https://github.com/taikoxyz
-//   Discord: https://discord.gg/taikoxyz
-//   Twitter: https://twitter.com/taikoxyz
-//   Blog: https://mirror.xyz/labs.taiko.eth
-//   Youtube: https://www.youtube.com/@taikoxyz
-
 pragma solidity 0.8.24;
 
 import "./TaikoData.sol";

packages/protocol/contracts/L1/TaikoData.sol

@@ -1,23 +1,10 @@
 // SPDX-License-Identifier: MIT
-//  _____     _ _         _         _
-// |_   _|_ _(_) |_____  | |   __ _| |__ ___
-//   | |/ _` | | / / _ \ | |__/ _` | '_ (_-<
-//   |_|\__,_|_|_\_\___/ |____\__,_|_.__/__/
-//
-//   Email: [email protected]
-//   Website: https://taiko.xyz
-//   GitHub: https://github.com/taikoxyz
-//   Discord: https://discord.gg/taikoxyz
-//   Twitter: https://twitter.com/taikoxyz
-//   Blog: https://mirror.xyz/labs.taiko.eth
-//   Youtube: https://www.youtube.com/@taikoxyz
-
 pragma solidity 0.8.24;
 
 /// @title TaikoData
-/// @custom:security-contact [email protected]
 /// @notice This library defines various data structures used in the Taiko
 /// protocol.
+/// @custom:security-contact [email protected]
 library TaikoData {
     /// @dev Struct holding Taiko configuration parameters. See {TaikoConfig}.
     struct Config {

packages/protocol/contracts/L1/TaikoErrors.sol

@@ -1,27 +1,14 @@
 // SPDX-License-Identifier: MIT
-//  _____     _ _         _         _
-// |_   _|_ _(_) |_____  | |   __ _| |__ ___
-//   | |/ _` | | / / _ \ | |__/ _` | '_ (_-<
-//   |_|\__,_|_|_\_\___/ |____\__,_|_.__/__/
-//
-//   Email: [email protected]
-//   Website: https://taiko.xyz
-//   GitHub: https://github.com/taikoxyz
-//   Discord: https://discord.gg/taikoxyz
-//   Twitter: https://twitter.com/taikoxyz
-//   Blog: https://mirror.xyz/labs.taiko.eth
-//   Youtube: https://www.youtube.com/@taikoxyz
-
 pragma solidity 0.8.24;
 
 /// @title TaikoErrors
-/// @custom:security-contact [email protected]
-/// @notice This abstract contract provides custom error declartions used in
+/// @notice This abstract contract provides custom error declarations used in
 /// the Taiko protocol. Each error corresponds to specific situations where
 /// exceptions might be thrown.
+/// @dev The errors defined here must match the definitions in the corresponding
+/// L1 libraries.
+/// @custom:security-contact [email protected]
 abstract contract TaikoErrors {
-    // NOTE: The following custom errors must match the definitions in
-    // `L1/libs/*.sol`.
     error L1_ALREADY_CONTESTED();
     error L1_ALREADY_PROVED();
     error L1_ASSIGNED_PROVER_NOT_ALLOWED();

packages/protocol/contracts/L1/TaikoEvents.sol

@@ -1,28 +1,15 @@
 // SPDX-License-Identifier: MIT
-//  _____     _ _         _         _
-// |_   _|_ _(_) |_____  | |   __ _| |__ ___
-//   | |/ _` | | / / _ \ | |__/ _` | '_ (_-<
-//   |_|\__,_|_|_\_\___/ |____\__,_|_.__/__/
-//
-//   Email: [email protected]
-//   Website: https://taiko.xyz
-//   GitHub: https://github.com/taikoxyz
-//   Discord: https://discord.gg/taikoxyz
-//   Twitter: https://twitter.com/taikoxyz
-//   Blog: https://mirror.xyz/labs.taiko.eth
-//   Youtube: https://www.youtube.com/@taikoxyz
-
 pragma solidity 0.8.24;
 
 import "./TaikoData.sol";
 
 /// @title TaikoEvents
-/// @custom:security-contact [email protected]
 /// @notice This abstract contract provides event declarations for the Taiko
 /// protocol, which are emitted during block proposal, proof, verification, and
 /// Ethereum deposit processes.
 /// @dev The events defined here must match the definitions in the corresponding
 /// L1 libraries.
+/// @custom:security-contact [email protected]
 abstract contract TaikoEvents {
     /// @dev Emitted when a block is proposed.
     /// @param blockId The ID of the proposed block.

packages/protocol/contracts/L1/TaikoL1.sol

@@ -1,17 +1,4 @@
 // SPDX-License-Identifier: MIT
-//  _____     _ _         _         _
-// |_   _|_ _(_) |_____  | |   __ _| |__ ___
-//   | |/ _` | | / / _ \ | |__/ _` | '_ (_-<
-//   |_|\__,_|_|_\_\___/ |____\__,_|_.__/__/
-//
-//   Email: [email protected]
-//   Website: https://taiko.xyz
-//   GitHub: https://github.com/taikoxyz
-//   Discord: https://discord.gg/taikoxyz
-//   Twitter: https://twitter.com/taikoxyz
-//   Blog: https://mirror.xyz/labs.taiko.eth
-//   Youtube: https://www.youtube.com/@taikoxyz
-
 pragma solidity 0.8.24;
 
 import "../common/EssentialContract.sol";
@@ -24,15 +11,14 @@ import "./TaikoErrors.sol";
 import "./TaikoEvents.sol";
 
 /// @title TaikoL1
-/// @custom:security-contact [email protected]
+/// @notice This contract serves as the "base layer contract" of the Taiko protocol, providing
+/// functionalities for proposing, proving, and verifying blocks. The term "base layer contract"
+/// means that although this is usually deployed on L1, it can also be deployed on L2s to create
+/// L3 "inception layers". The contract also handles the deposit and withdrawal of Taiko tokens
+/// and Ether. Additionally, this contract doesn't hold any Ether. Ether deposited to L2 are held
+/// by the Bridge contract.
 /// @dev Labeled in AddressResolver as "taiko"
-/// @notice This contract serves as the "base layer contract" of the Taiko
-/// protocol, providing functionalities for proposing, proving, and verifying
-/// blocks. The term "base layer contract" means that although this is usually
-/// deployed on L1, it can also be deployed on L2s to create L3s ("inception
-/// layers"). The contract also handles the deposit and withdrawal of Taiko
-/// tokens and Ether.
-/// This contract doesn't hold any Ether. Ether deposited to L2 are held by the Bridge contract.
+/// @custom:security-contact [email protected]
 contract TaikoL1 is EssentialContract, ITaikoL1, ITierProvider, TaikoEvents, TaikoErrors {
     TaikoData.State public state;
     uint256[50] private __gap;

packages/protocol/contracts/L1/TaikoToken.sol

@@ -1,17 +1,4 @@
 // SPDX-License-Identifier: MIT
-//  _____     _ _         _         _
-// |_   _|_ _(_) |_____  | |   __ _| |__ ___
-//   | |/ _` | | / / _ \ | |__/ _` | '_ (_-<
-//   |_|\__,_|_|_\_\___/ |____\__,_|_.__/__/
-//
-//   Email: [email protected]
-//   Website: https://taiko.xyz
-//   GitHub: https://github.com/taikoxyz
-//   Discord: https://discord.gg/taikoxyz
-//   Twitter: https://twitter.com/taikoxyz
-//   Blog: https://mirror.xyz/labs.taiko.eth
-//   Youtube: https://www.youtube.com/@taikoxyz
-
 pragma solidity 0.8.24;
 
 import "@openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol";
@@ -20,11 +7,11 @@ import "@openzeppelin/contracts-upgradeable/token/ERC20/extensions/ERC20VotesUpg
 import "../common/EssentialContract.sol";
 
 /// @title TaikoToken
-/// @custom:security-contact [email protected]
-/// @dev Labeled in AddressResolver as "taiko_token"
 /// @notice The TaikoToken (TKO), in the protocol is used for prover collateral
 /// in the form of bonds. It is an ERC20 token with 18 decimal places of
 /// precision.
+/// @dev Labeled in AddressResolver as "taiko_token"
+/// @custom:security-contact [email protected]
 contract TaikoToken is EssentialContract, ERC20SnapshotUpgradeable, ERC20VotesUpgradeable {
     uint256[50] private __gap;
 

packages/protocol/contracts/L1/gov/TaikoGovernor.sol

@@ -1,17 +1,4 @@
 // SPDX-License-Identifier: MIT
-//  _____     _ _         _         _
-// |_   _|_ _(_) |_____  | |   __ _| |__ ___
-//   | |/ _` | | / / _ \ | |__/ _` | '_ (_-<
-//   |_|\__,_|_|_\_\___/ |____\__,_|_.__/__/
-//
-//   Email: [email protected]
-//   Website: https://taiko.xyz
-//   GitHub: https://github.com/taikoxyz
-//   Discord: https://discord.gg/taikoxyz
-//   Twitter: https://twitter.com/taikoxyz
-//   Blog: https://mirror.xyz/labs.taiko.eth
-//   Youtube: https://www.youtube.com/@taikoxyz
-
 pragma solidity 0.8.24;
 
 import "@openzeppelin/contracts-upgradeable/governance/GovernorUpgradeable.sol";

packages/protocol/contracts/L1/gov/TaikoTimelockController.sol

@@ -1,17 +1,4 @@
 // SPDX-License-Identifier: MIT
-//  _____     _ _         _         _
-// |_   _|_ _(_) |_____  | |   __ _| |__ ___
-//   | |/ _` | | / / _ \ | |__/ _` | '_ (_-<
-//   |_|\__,_|_|_\_\___/ |____\__,_|_.__/__/
-//
-//   Email: [email protected]
-//   Website: https://taiko.xyz
-//   GitHub: https://github.com/taikoxyz
-//   Discord: https://discord.gg/taikoxyz
-//   Twitter: https://twitter.com/taikoxyz
-//   Blog: https://mirror.xyz/labs.taiko.eth
-//   Youtube: https://www.youtube.com/@taikoxyz
-
 pragma solidity 0.8.24;
 
 import "@openzeppelin/contracts-upgradeable/governance/TimelockControllerUpgradeable.sol";

packages/protocol/contracts/L1/hooks/AssignmentHook.sol

@@ -1,17 +1,4 @@
 // SPDX-License-Identifier: MIT
-//  _____     _ _         _         _
-// |_   _|_ _(_) |_____  | |   __ _| |__ ___
-//   | |/ _` | | / / _ \ | |__/ _` | '_ (_-<
-//   |_|\__,_|_|_\_\___/ |____\__,_|_.__/__/
-//
-//   Email: [email protected]
-//   Website: https://taiko.xyz
-//   GitHub: https://github.com/taikoxyz
-//   Discord: https://discord.gg/taikoxyz
-//   Twitter: https://twitter.com/taikoxyz
-//   Blog: https://mirror.xyz/labs.taiko.eth
-//   Youtube: https://www.youtube.com/@taikoxyz
-
 pragma solidity 0.8.24;
 
 import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
@@ -22,8 +9,8 @@ import "../ITaikoL1.sol";
 import "./IHook.sol";
 
 /// @title AssignmentHook
+/// @notice A hook that handles prover assignment verification and fee processing.
 /// @custom:security-contact [email protected]
-/// A hook that handles prover assignment varification and fee processing.
 contract AssignmentHook is EssentialContract, IHook {
     using LibAddress for address;
     using SafeERC20 for IERC20;

packages/protocol/contracts/L1/hooks/IHook.sol

@@ -1,17 +1,4 @@
 // SPDX-License-Identifier: MIT
-//  _____     _ _         _         _
-// |_   _|_ _(_) |_____  | |   __ _| |__ ___
-//   | |/ _` | | / / _ \ | |__/ _` | '_ (_-<
-//   |_|\__,_|_|_\_\___/ |____\__,_|_.__/__/
-//
-//   Email: [email protected]
-//   Website: https://taiko.xyz
-//   GitHub: https://github.com/taikoxyz
-//   Discord: https://discord.gg/taikoxyz
-//   Twitter: https://twitter.com/taikoxyz
-//   Blog: https://mirror.xyz/labs.taiko.eth
-//   Youtube: https://www.youtube.com/@taikoxyz
-
 pragma solidity 0.8.24;
 
 import "../TaikoData.sol";

packages/protocol/contracts/L1/libs/LibDepositing.sol

@@ -1,17 +1,4 @@
 // SPDX-License-Identifier: MIT
-//  _____     _ _         _         _
-// |_   _|_ _(_) |_____  | |   __ _| |__ ___
-//   | |/ _` | | / / _ \ | |__/ _` | '_ (_-<
-//   |_|\__,_|_|_\_\___/ |____\__,_|_.__/__/
-//
-//   Email: [email protected]
-//   Website: https://taiko.xyz
-//   GitHub: https://github.com/taikoxyz
-//   Discord: https://discord.gg/taikoxyz
-//   Twitter: https://twitter.com/taikoxyz
-//   Blog: https://mirror.xyz/labs.taiko.eth
-//   Youtube: https://www.youtube.com/@taikoxyz
-
 pragma solidity 0.8.24;
 
 import "../../common/IAddressResolver.sol";
@@ -20,8 +7,8 @@ import "../../libs/LibMath.sol";
 import "../TaikoData.sol";
 
 /// @title LibDepositing
-/// @custom:security-contact [email protected]
 /// @notice A library for handling Ether deposits in the Taiko protocol.
+/// @custom:security-contact [email protected]
 library LibDepositing {
     using LibAddress for address;
     using LibAddress for address payable;

packages/protocol/contracts/L1/libs/LibProposing.sol

@@ -1,17 +1,4 @@
 // SPDX-License-Identifier: MIT
-//  _____     _ _         _         _
-// |_   _|_ _(_) |_____  | |   __ _| |__ ___
-//   | |/ _` | | / / _ \ | |__/ _` | '_ (_-<
-//   |_|\__,_|_|_\_\___/ |____\__,_|_.__/__/
-//
-//   Email: [email protected]
-//   Website: https://taiko.xyz
-//   GitHub: https://github.com/taikoxyz
-//   Discord: https://discord.gg/taikoxyz
-//   Twitter: https://twitter.com/taikoxyz
-//   Blog: https://mirror.xyz/labs.taiko.eth
-//   Youtube: https://www.youtube.com/@taikoxyz
-
 pragma solidity 0.8.24;
 
 import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
@@ -23,8 +10,8 @@ import "../TaikoData.sol";
 import "./LibDepositing.sol";
 
 /// @title LibProposing
-/// @custom:security-contact [email protected]
 /// @notice A library for handling block proposals in the Taiko protocol.
+/// @custom:security-contact [email protected]
 library LibProposing {
     using LibAddress for address;