Automatically identify missing or incomplete natspec
npm install @defi-wonderland/natspec-smells
Just like code, documentation can smell too.
Natspec Smells aims to help automatically identify missing or incomplete natspec.
What can it do?
- Verifies natspec for: constructors, variables, functions, ~~structs~~, errors, events, modifiers
- Finds misspelled or missing @param or @return's.
- Lets you enforce the need for @inheritdoc in public/external functions.
- Can integrate on your daily workflow, or just as a final check.
Want to quickly check if your natspec smells?
Just run:
``
npx @defi-wonderland/natspec-smells --include "src/*/.sol"
> [!NOTE]
> Remember to put quotes around the glob strings when using the include and exclude options.
1. Install the package:
`bash`
yarn add --dev @defi-wonderland/natspec-smells
2. Create a config file named natspec-smells.config.js, you can use the following as an example:
`javascript
/**
* List of supported options: https://github.com/defi-wonderland/natspec-smells?tab=readme-ov-file#options
*/
/* @type {import('@defi-wonderland/natspec-smells').Config} /
module.exports = {
include: 'src/*/.sol',
exclude: '(test|scripts)/*/.sol',
};
`
3. Run
`bash`
yarn natspec-smells
With the setup defined above, it's possible to invoke the executable from within a github workflow, as long as node.js is available in that environment:
`
steps:
- uses: actions/checkout@v3
- name: Use Node.js
uses: actions/setup-node@v3
- name: Check natspec
run: yarn natspec-smells
`
| Option | Description | Required | Default |
| -------------------- | ------------------------------------------------------------------ | -------- | ------- |
| include | Glob pattern of files to process. | Yes | |exclude
| | Glob pattern of files to exclude. | No | "" |root
| | Project root directory. | No | ./ |enforceInheritdoc
| | True if all external and public functions should have @inheritdoc. | No | true |constructorNatspec
| | True if the constructor should have natspec. | No | false` |
Natspec Smells was built with ❤️ by Wonderland.
Wonderland the largest core development group in web3. Our commitment is to a financial future that's open, decentralized, and accessible to all.
DeFi sucks, but Wonderland is here to make it better.