From b1693910cdb91a9526b13f58107dd7e36b4073ba Mon Sep 17 00:00:00 2001 From: b00ste Date: Tue, 6 Jun 2023 11:22:39 +0300 Subject: [PATCH] Prepare release 0.3.0 --- .github/workflows/release-package.yml | 33 --------------- README.md | 59 +++++++++++++++------------ package.json | 7 +--- 3 files changed, 36 insertions(+), 63 deletions(-) delete mode 100644 .github/workflows/release-package.yml diff --git a/.github/workflows/release-package.yml b/.github/workflows/release-package.yml deleted file mode 100644 index 3ce152d..0000000 --- a/.github/workflows/release-package.yml +++ /dev/null @@ -1,33 +0,0 @@ -name: Node.js Package - -on: - release: - types: [created] - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - with: - node-version: 16 - - run: npm ci - - run: npm build - - publish-gpr: - needs: build - runs-on: ubuntu-latest - permissions: - packages: write - contents: read - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - with: - node-version: 16 - registry-url: https://npm.pkg.github.com/ - - run: npm ci - - run: npm publish - env: - NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}} diff --git a/README.md b/README.md index 1d02e81..c82c23e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Dodoc -![version](https://img.shields.io/npm/v/@primitivefi/hardhat-dodoc) ![npm](https://img.shields.io/npm/dt/@primitivefi/hardhat-dodoc) ![license](https://img.shields.io/npm/l/@primitivefi/hardhat-dodoc) +![version](https://img.shields.io/npm/v/@b00ste/hardhat-dodoc) ![npm](https://img.shields.io/npm/dt/@b00ste/hardhat-dodoc) ![license](https://img.shields.io/npm/l/@b00ste/hardhat-dodoc) Zero-config Hardhat plugin to generate documentation for all your Solidity contracts. @@ -18,20 +18,20 @@ First thing to do is to install the plugin in your Hardhat project: ```bash # Using yarn -yarn add @primitivefi/hardhat-dodoc +yarn add @b00ste/hardhat-dodoc # Or using npm -npm i @primitivefi/hardhat-dodoc +npm i @b00ste/hardhat-dodoc ``` Next step is simply to include the plugin into your `hardhat.config.js` or `hardhat.config.ts` file: ```typescript // Using JavaScript -require('@primitivefi/hardhat-dodoc'); +require('@b00ste/hardhat-dodoc'); // Using ES6 or TypeScript -import '@primitivefi/hardhat-dodoc'; +import '@b00ste/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. @@ -45,6 +45,9 @@ The only requirement to use Dodoc is to comment your Solidity contracts using [N /// @dev More info about doing another thing when the function is called. /// @param num A random number /// @return A random variable +/// @custom:requirement Must be at lease 18 years old to use this function. +/// @custom:danger Another thing is extremely random, use at your own risk! +/// @custom:info Another thing 2 coming soon. function anotherThing(uint256 num) external pure returns (uint256); ``` @@ -60,19 +63,25 @@ Dodoc will take care of everything and will generate the following output: > > Does another thing when the function is called. > -> *More info about doing another thing when the function is called.* +> _More info about doing another thing when the function is called._ +> +> **Requirement:** _Must be at lease 18 years old to use this function._ +> +> **Danager:** _Another thing is extremely random, use at your own risk!_ +> +> **Info:** _Another thing 2 coming soon._ > > #### Parameters > -> | Name | Type | Description | -> |---|---|---| -> | num | uint256 | A random number | +> | Name | Type | Description | +> | ---- | ------- | --------------- | +> | num | uint256 | A random number | > > #### Returns > -> | Name | Type | Description | -> |---|---|---| -> | _0 | uint256 | A random variable | +> | 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. @@ -94,7 +103,7 @@ Dodoc comes with a default configuration but you can still tweak some parameters import { HardhatUserConfig } from 'hardhat/config'; import '@nomiclabs/hardhat-waffle'; import '@nomiclabs/hardhat-ethers'; -import '@primitivefi/hardhat-dodoc'; +import '@b00ste/hardhat-dodoc'; const config: HardhatUserConfig = { // Your Hardhat config... @@ -110,16 +119,17 @@ 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` | +| 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` | +| `helpers` | List of objects with `helperName` & `helperFunc`, `helperFunc` MUST be of type [**HelperFunction**](https://squirrellyjs.github.io/squirrelly/modules/_containers_.html#helperfunction) from _squirrelly.js_ | `[]` | ## 💅 Customize @@ -132,8 +142,7 @@ Once you're satisfied, simply refer to your template using the `templatePath` pa ## ⛑ 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). diff --git a/package.json b/package.json index 2065817..d151f1a 100644 --- a/package.json +++ b/package.json @@ -1,15 +1,12 @@ { - "name": "@b00ste/primitive-dodoc", + "name": "@b00ste/hardhat-dodoc", "version": "0.3.0", "description": "Zero-config Hardhat plugin to generate documentation for all your Solidity contracts", - "repository": "github:b00ste/primitive-dodoc", + "repository": "github:b00ste/hardhat-dodoc", "author": "Primitive", "license": "MIT", "main": "dist/src/index.js", "types": "dist/src/index.d.ts", - "publishConfig": { - "@b00ste:registry": "https://npm.pkg.github.com" - }, "keywords": [ "ethereum", "smart-contracts",