title | version | authors | license |
---|---|---|---|
DAppSpec |
v2022.06.26, v2022.07.13, v2022.07.19 |
<TBD> |
CC-SA-2.5 |
NEW: OCI for Contracts OLD: NatSpec for frontend usage + Admonitions as @custom:tags
/**
* @custom:org.label-schema.security='[email protected]'
* @custom:org.label-schema.support='github.com/manifoldfinance/support'
* @custom:org.label-schema.vcs-url='github.com/manifoldfinance'
* @custom:org.label-schema.vendor='CommodityStream, Inc'
* @custom:org.label-schema.schema-version="1.0"
*/
Dappspec takes the @custom:...
natspec tag and provides a list of admonitions for generating documentation for Solidity contracts.
-
The Specifics Admonitions include identifiers for codeblocks that reference
gas
optimizations,assembly
blocks, andemit
events. -
The
@custom:security
tag as used by OpenZeppelin for identifiying the point of contact. Similar tosecurity.txt
, see an example here -
The General Admonitions are meant to render the docstring content as a code block that you would find in generators like
mkdocs
. see squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types
The following SHOULD
trigger an error:
-
A
public
orexternal
function which does not have a NatSpec comment- NatSpec comment does not have a
@notice
set - NatSpec comment does not have a
@param
for every parameter - NatSpec comment does not have a
@return
for every return
- NatSpec comment does not have a
-
A
public
storage variable which does not have a NatSpec comment- NatSpec comment does not have a
@notice
set - NatSpec comment does not have a
@param
for every parameter - NatSpec comment does not have a
@return
for every return
- NatSpec comment does not have a
-
An
Error
type which does not have a NatSpec comment- NatSpec commend does not have a
@notice
set
- NatSpec commend does not have a
The Solidity project recommends the above. It is extremely useful. And few people do it. So it will be very helpful to add rules for it.
It is recommended that Solidity contracts are fully annotated using NatSpec for all public interfaces (everything in the ABI). docs.soliditylang.org/en/v0.8.6/style-guide.html?highlight=style%20guide#natspec
-
An
internal
function which does not have a NatSpec comment- NatSpec comment does not have a
@param
for every parameter - NatSpec comment does not have a
@return
for every return
- NatSpec comment does not have a
Note that @notice
is not required in this circumstance because that tag applies to "end users" whereas an internal
function is useful only to contract developers.
Note that private
functions are not included in this rule. This is because documentation for implementation details is always less important that documentation for an objects' surface area. If you like, this could be another rule natspec-documentation-private
and should be default OFF.
Note
Credit to fulldecent, see this comment
- French
:::note{label="Il ne faut rien laisser au hasard."} Battre le fer pendant qu’il est chaud. :::
Warning
GitHub Warning
Note
GitHub Note
- check
- important
- warning, caution, attention
- gas
- assembly
- emit
- security
md-code-hl
number-color special-color function-color constant-color keyword-color string-color name-color operator-color punctuation-color comment-color generic-color variable-color
// try / catch flashloan arb. In case arb reverts, user swap will still succeed.
try bento.flashLoan(IFlashBorrower(address(this)), address(this), output, amountIn, params) {
/// @custom:emit MEV success
emit MEV(msg.sender, output, optimalReturns - ((amountIn * 5) / 10000));
} catch {
/// @custom:emit MEV fail flashloan
emit LoanError(output, amountIn);
/// @custom:gas Uint256 zero check gas saver
/// @notice Uint256 zero check gas saver
/// @param value Number to check
function _isZero(uint256 value) internal pure returns (bool boolValue) {
assembly {
boolValue := iszero(value)
}
}
/// @custom:gas Uint256 not zero check gas saver
/// @notice Uint256 not zero check gas saver
/// @param value Number to check
function _isNonZero(uint256 value) internal pure returns (bool boolValue) {
assembly {
boolValue := iszero(iszero(value))
}
}
abstract contract ERC2771Context is Context {
/// @custom:oz-upgrades-unsafe-allow state-variable-immutable
address private immutable _trustedForwarder;
/// @custom:oz-upgrades-unsafe-allow constructor
constructor(address trustedForwarder) {
_trustedForwarder = trustedForwarder;
}