Socket
Socket
Sign inDemoInstall

@primitivefi/hardhat-dodoc

Package Overview
Dependencies
1
Maintainers
3
Versions
8
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@primitivefi/hardhat-dodoc


Version published
Maintainers
3
Created

Readme

Source

Dodoc

version npm license

Zero-config Hardhat plugin to generate documentation for all your Solidity contracts.

  • 🤪 Zero-configuration required
  • ✅ Compatible with latest Solidity versions (>= 0.8.0)
  • 🔍 Supports events, errors and external / public functions
  • 📖 Default output to Markdown
  • 🔧 Extendable using custom templates

Want to see a live example? Check out Primitive documentation!

📦 Installation

First thing to do is to install the plugin in your Hardhat project:

# Using yarn
yarn add @primitivefi/hardhat-dodoc

# Or using npm
npm i @primitivefi/hardhat-dodoc

Next step is simply to include the plugin into your hardhat.config.js or hardhat.config.ts file:

// Using JavaScript
require('@primitivefi/hardhat-dodoc');

// Using ES6 or TypeScript
import '@primitivefi/hardhat-dodoc';

And you're done! Documentation will be automatically generated on the next compilation and saved into the docs folder at the root of your project.

📝 Usage

The only requirement to use Dodoc is to comment your Solidity contracts using NatSpec format. For example, given the following function:

/// @notice Does another thing when the function is called.
/// @dev More info about doing another thing when the function is called.
/// @param num A random number
/// @return A random variable
function anotherThing(uint256 num) external pure returns (uint256);

Dodoc will take care of everything and will generate the following output:

Methods

anotherThing

function anotherThing(uint256 num) external pure returns (uint256)

Does another thing when the function is called.

More info about doing another thing when the function is called.

Parameters
NameTypeDescription
numuint256A random number
Returns
NameTypeDescription
_0uint256A random variable

Dodoc is compatible with all the NatSpec tags (except custom ones for now), and can generate documentation for events, custom errors and external / public functions.

By default Dodoc generates new documentation after each compilation, but you can also trigger the task with the following command:

# Using yarn
yarn hardhat dodoc

# Or using npx
npx hardhat dodoc

🔧 Config

Dodoc comes with a default configuration but you can still tweak some parameters. To do it, change your Hardhat config file like this:

import { HardhatUserConfig } from 'hardhat/config';
import '@nomiclabs/hardhat-waffle';
import '@nomiclabs/hardhat-ethers';
import '@primitivefi/hardhat-dodoc';

const config: HardhatUserConfig = {
  // Your Hardhat config...
  dodoc: {
    runOnCompile: true,
    debugMode: true,
    // More options...
  },
};

export default config;

Here are all the configuration parameters that are currently available, but as said above, all of them are entirely optional:

ParameterDescriptionDefault value
runOnCompileTrue if the plugin should generate the documentation on every compilationtrue
includeList of all the contract / interface / library / folder names to include in the documentation generation. An empty array will generate documentation for everything[]
excludeList of all the contract / interface / library / folder names to exclude from the documentation generation[]
outputDirOutput directory of the documentationdocs
templatePathPath to the documentation template./template.sqrl
debugModeTest mode generating additional JSON files used for debuggingfalse
keepFileStructureTrue if you want to preserve your contracts file structure in the output directorytrue
freshOutputTrue if you want to clean the output directory before generating new documentationtrue

💅 Customize

Dodoc integrates a super cool template engine called SquirrellyJS, allowing anyone to create new output formats easily.

You can checkout the default Markdown template to get some inspiration, as well as SquirrellyJS documentation to learn more about it. Feel free to be creative, any kind of output such as Markdown, MDX, HTML or even JSON is supported!

Once you're satisfied, simply refer to your template using the templatePath parameter in your configuration and Dodoc will use it to output the documentation!

⛑ Help

Feel free to open an issue if you need help or if you encounter a problem! Here are some already known problems though:

  • Due to the technical limitations of the Solidity compiler, the documentation of private and internal functions is not rendered. Hence, the documentation of libraries might be close to empty!
  • Functions that are not commented at all might not be rendered.
  • State variables overriding functions defined by an interface might "erase" the name of the parameters. A current workaround is to name the function parameters using the _0, _1, ... format.
  • Special functions such as constructor, fallback and receive might not be rendered.
  • Custom NatSpec tags @custom:... are not rendered (yet).

Keywords

FAQs

Last updated on 07 Mar 2022

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc