• Stars
    star
    135
  • Rank 269,297 (Top 6 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created about 3 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

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

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

Name Type Description
num uint256 A random number

Returns

Name Type Description
_0 uint256 A 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:

Parameter Description Default value
runOnCompile True if the plugin should generate the documentation on every compilation true
include List of all the contract / interface / library / folder names to include in the documentation generation. An empty array will generate documentation for everything []
exclude List of all the contract / interface / library / folder names to exclude from the documentation generation []
outputDir Output directory of the documentation docs
templatePath Path to the documentation template ./template.sqrl
debugMode Test mode generating additional JSON files used for debugging false
keepFileStructure True if you want to preserve your contracts file structure in the output directory true
freshOutput True if you want to clean the output directory before generating new documentation true

💅 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).

More Repositories

1

arbiter

A blazing-fast Ethereum sandbox that lets developers orchestrate event-driven simulations.
Rust
669
star
2

hardhat-marmite

🥘 Hassle-free Hardhat plugin to compare gas cost among different Solidity code snippets.
TypeScript
196
star
3

rmm-core

Primitive Replicating Market Maker smart contracts
Solidity
131
star
4

solstat

Math library written in solidity for statistical function approximations like the Normal Cumulative Distribution Function.
Solidity
118
star
5

portfolio

Portfolio is an automated market making protocol for implementing custom strategies at the lowest cost possible.
Solidity
113
star
6

hardhat-foundry

Forkable hardhat & foundry template for thorough evm development.
Solidity
87
star
7

soulbound

Implementation of a non-transferrable NFT using non-financial incentivization.
Solidity
85
star
8

rmms-py

Python simulator to test implementation of the RMMS paper results.
Python
55
star
9

RMM01-Simulations

RMM-01 Simulations
Python
50
star
10

arbiter-template

Minimal template for simulating contracts with arbiter.
Rust
45
star
11

v1-contracts

Primitive protocol solidity contracts.
Solidity
43
star
12

rmm-manager

Manager and Routing smart contracts for Primitive RMM
Solidity
34
star
13

univ3-kit

An open simulation for Uniswap V3 contracts
Rust
34
star
14

sybil-detection

Python
31
star
15

open-research-questions

This is a collection of open research questions in the DeFi mechanism design space pertinent to the Primitive R&D Team. This serves as a public forum and is open to discussion and changes amongst the broader DeFi research and development community.
26
star
16

excalibur

Excalibur
Rust
21
star
17

rmm-math

Typescript math library for cumulative distributions, black-scholes, and the RMM trading function.
TypeScript
21
star
18

proto-sim-portfolio

Prototype risk modeling simulation for Portfolio using Arbiter.
Rust
20
star
19

DFMM

Smart contracts of the DFMM protocol
Rust
18
star
20

rmm-ethers

Library for interacting with RMM protocol through ethers.js.
TypeScript
15
star
21

aika

Discrete event simulator built in Rust 🦀
Rust
13
star
22

Topological-Data-Analysis

This repository is for topologic and geometric data analysis.
Python
13
star
23

m3-rs

Simple rust interface to get derived analytical information of algorithmic market making models (M3).
Rust
12
star
24

portfolio_simulations

Moving to the new Arbiter framework to test Portfolio.
Rust
10
star
25

rmm-sdk

Typescript based entity classes and transaction builders for the rmm-core and rmm-periphery smart contracts.
TypeScript
10
star
26

rmm-examples

Solidity
10
star
27

portfolio-rs

SDK for the Portfolio protocol written in rust.
Rust
9
star
28

DisputeGameSimulations

Rust
9
star
29

v1-connectors

Smart contracts that connect Primitive V1 to other Ethereum protocols and standards.
Solidity
9
star
30

CFMMRouter.py

Python implementation of CFMMRouter.jl
Python
9
star
31

visualization-rs

This is a collection of math and plotting tools for us to use for visualizing data.
Rust
8
star
32

rmm-docs

Primitive and RMM Protocol Documentation - Crypto Derivatives without Counterparties
JavaScript
7
star
33

fvm.ts

TypeScript
4
star
34

pool-analytics

Jupyter Notebook
4
star
35

v1-interface

An open-source interface for the Primitive protocol.
TypeScript
4
star
36

dagger

A lightweight interface for the DFMM smart contracts
TypeScript
4
star
37

Research

Research papers and repository directory
3
star
38

v1-sdk

An SDK for the Primitive Protocol.
TypeScript
3
star
39

portfolio-ts

Minimal toolkit for building TypeScript based applications for Portfolio by Primitive.
TypeScript
3
star
40

Arbitrum-Transaction-Data-Analysis

This repository is for transaction data analysis on the the Arbitrum Network
3
star
41

amm-auction

Solidity
3
star
42

portfolio-examples-solidity

Solidity
3
star
43

arbmod

git submodule for arbiter
Solidity
3
star
44

v1-subgraph

A graph for the Primitive Protocol.
TypeScript
3
star
45

dfmm-indexer

Indexer for the DFMM protocol
TypeScript
3
star
46

security

All security reports for Primitive products and protocols.
2
star
47

discord-bot

TypeScript
2
star
48

rmm-core-dapptools

Rmm protocol core contracts in dapptools testing environment.
Solidity
2
star
49

arbiter-dispute-game

TeX
2
star
50

brand

Primitive's brand assets.
2
star
51

v1-amm-spec

Derivative focused AMM for the Primitive Protocol.
Solidity
2
star
52

arbiter-portfolio-sim

Migration from old middleware to new.
Solidity
1
star
53

rmm

Solidity
1
star
54

nugu

Solidity
1
star
55

fee-generation-py

Python
1
star