From a0f48c234b51d35c0ab55d34834a7dc0abdcd7ad Mon Sep 17 00:00:00 2001 From: b00ste Date: Thu, 3 Aug 2023 11:20:24 +0300 Subject: [PATCH] chore: add suggested changes --- .eslintrc.js | 8 +- README.md | 1 - .../SomeOtherLibrary/SomeOtherLibrary.sol | 14 +- examples/docs/contracts/Bar.json | 308 +++++++++--------- examples/docs/contracts/Bar.md | 130 +++----- examples/docs/contracts/ExampleContract.json | 266 +++++++-------- examples/docs/contracts/ExampleContract.md | 120 +++---- examples/docs/contracts/FallbackContract.json | 50 +-- examples/docs/contracts/FallbackContract.md | 28 +- examples/docs/contracts/IBar.json | 132 ++++---- examples/docs/contracts/IBar.md | 74 ++--- examples/docs/contracts/IExampleContract.json | 206 ++++++------ examples/docs/contracts/IExampleContract.md | 90 ++--- .../SomeOtherLibrary/SomeOtherLibrary.json | 164 +++++----- .../SomeOtherLibrary/SomeOtherLibrary.md | 111 +++---- .../contracts/subfolder/AnotherContract.json | 48 +-- .../contracts/subfolder/AnotherContract.md | 28 +- examples/docs/libraries/Foo.json | 50 +-- examples/docs/libraries/Foo.md | 32 +- examples/docs/libraries/IFoo.json | 50 +-- examples/docs/libraries/IFoo.md | 32 +- src/index.ts | 56 ++-- src/utils.ts | 20 +- 23 files changed, 878 insertions(+), 1140 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index e5f01fa..c75a4e4 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -5,17 +5,13 @@ module.exports = { mocha: true, node: true, }, - extends: [ - 'airbnb-base', - ], + extends: ['airbnb-base'], parser: '@typescript-eslint/parser', parserOptions: { ecmaVersion: 12, sourceType: 'module', }, - plugins: [ - '@typescript-eslint', - ], + plugins: ['@typescript-eslint'], rules: { 'import/extensions': ['error', 'never'], }, diff --git a/README.md b/README.md index 06001eb..bcf2bff 100644 --- a/README.md +++ b/README.md @@ -144,7 +144,6 @@ Once you're satisfied, simply refer to your template using the `templatePath` pa Feel free to open an issue if you need help or if you encounter a problem! Here are some already known problems though: -- If you're defining Errors in Libraries, please do that in the scope of the contract. - Due to the technical limitations of the Solidity compiler, the documentation of `private` functions is not rendered. - 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. diff --git a/examples/contracts/SomeOtherLibrary/SomeOtherLibrary.sol b/examples/contracts/SomeOtherLibrary/SomeOtherLibrary.sol index 7f4ddfb..52e5d80 100644 --- a/examples/contracts/SomeOtherLibrary/SomeOtherLibrary.sol +++ b/examples/contracts/SomeOtherLibrary/SomeOtherLibrary.sol @@ -9,13 +9,17 @@ error SomeError(bytes32 invalidHash); /// @notice Some Other Error fired!!!! error SomeOtherError(); -/// @dev this is the third error. +/// @dev This is the third error. +/// The error does the following things: +/// - Shows you the `functionSelector`. +/// - Shows you the `functionMask`. +/// - Shows you an error. /// @custom:danger Be careful, this Error is dangerous! /// @param functionSelector This is a function selector -/// @param fucntionMask This is a function mask -error ThirdError(bytes4 functionSelector, uint256 fucntionMask); +/// @param functionMask This is a function mask +error ThirdError(bytes4 functionSelector, uint256 functionMask); -error WhateverError(bytes16 somethingElse); +error ErrorWithoutNatspec(bytes16 somethingElse); library SomeOtherLibrary { /// @dev This function uses `keccak256(..)` to hash text. @@ -32,4 +36,4 @@ library SomeOtherLibrary { function someOtherFunction(string memory someText) internal pure returns(bytes32 hash) { return sha256(bytes(someText)); } -} \ No newline at end of file +} diff --git a/examples/docs/contracts/Bar.json b/examples/docs/contracts/Bar.json index de1a4ab..6184dab 100644 --- a/examples/docs/contracts/Bar.json +++ b/examples/docs/contracts/Bar.json @@ -1,164 +1,164 @@ { - "methods": { - "constructor": { - "stateMutability": "nonpayable", - "code": "constructor(uint256 someNumber)", - "inputs": { - "someNumber": { - "type": "uint256", - "description": "The description of the parameter" - } - }, - "outputs": {}, - "notice": "This is the notice of the constructor", - "details": "This is a constructor", - "custom:tip": "A custom blah tag" - }, - "fallback()": { - "stateMutability": "nonpayable", - "code": "fallback(bytes calldata fallbackParam) external nonpayable returns (bytes memory testtest)", - "inputs": { - "fallbackParam": { - "type": "bytes", - "description": "some details about the param" - } - }, - "outputs": { - "testtest": { - "type": "bytes", - "description": "result some details about the result" - } - }, - "details": "This is a fallback", - "notice": "This is the notice of the fallback", - "custom:warning": "the fallback function can return some data via assembly, but it will not be abi-encoded\n ", - "custom:hey": "hey hey hey\n ", - "custom:ho": "ho ho ho" - }, - "baap(uint256,address)": { - "stateMutability": "nonpayable", - "code": "function baap(uint256 bar, address aar) external nonpayable", - "inputs": { - "bar": { - "type": "uint256", - "description": "Number of bar" - }, - "aar": { - "type": "address", - "description": "Address of aar" - } - }, - "outputs": {}, - "notice": "Baaps the yaps" - }, - "boop(uint256)": { - "stateMutability": "nonpayable", - "code": "function boop(uint256 bar) external nonpayable", - "inputs": { - "bar": { - "type": "uint256" - } - }, - "outputs": {}, - "notice": "Cool function bro", - "custom:requirement": "Check first requirementCheck second requirement" - }, - "boop(uint256,uint256)": { - "stateMutability": "nonpayable", - "code": "function boop(uint256 bar, uint256 bar2) external nonpayable", - "inputs": { - "bar": { - "type": "uint256" - }, - "bar2": { - "type": "uint256" - } - }, - "outputs": {}, - "notice": "Alt cool function bro" - }, - "hello(bytes)": { - "stateMutability": "nonpayable", - "code": "function hello(bytes someCallData) external nonpayable", - "inputs": { - "someCallData": { - "type": "bytes", - "description": "hello tic tac toe" - } - }, - "outputs": {} - }, - "set(tuple)": { - "stateMutability": "nonpayable", - "code": "function set(IBar.T t) external nonpayable", - "inputs": { - "t": { - "type": "IBar.T" - } - }, - "outputs": {} + "methods": { + "constructor": { + "stateMutability": "nonpayable", + "code": "constructor(uint256 someNumber)", + "inputs": { + "someNumber": { + "type": "uint256", + "description": "The description of the parameter" + } + }, + "outputs": {}, + "notice": "This is the notice of the constructor", + "details": "This is a constructor", + "custom:tip": "A custom blah tag" + }, + "fallback()": { + "stateMutability": "nonpayable", + "code": "fallback(bytes calldata fallbackParam) external nonpayable returns (bytes memory testtest)", + "inputs": { + "fallbackParam": { + "type": "bytes", + "description": "some details about the param" + } + }, + "outputs": { + "testtest": { + "type": "bytes", + "description": "result some details about the result" + } + }, + "details": "This is a fallback", + "notice": "This is the notice of the fallback", + "custom:warning": "the fallback function can return some data via assembly, but it will not be abi-encoded\n ", + "custom:hey": "hey hey hey\n ", + "custom:ho": "ho ho ho" + }, + "baap(uint256,address)": { + "stateMutability": "nonpayable", + "code": "function baap(uint256 bar, address aar) external nonpayable", + "inputs": { + "bar": { + "type": "uint256", + "description": "Number of bar" }, - "receive()": { - "stateMutability": "payable", - "code": "receive() external payable", - "inputs": {}, - "outputs": {}, - "details": "This is a `receive()` function", - "notice": "This is the notice of the `receive()` function", - "custom:info": "if sending native tokens with some graffiti, check the {`fallback()`} function documentation." + "aar": { + "type": "address", + "description": "Address of aar" } + }, + "outputs": {}, + "notice": "Baaps the yaps" }, - "events": { - "Transfer": { - "code": "event Transfer(uint256 foo)", - "inputs": { - "foo": { - "type": "uint256", - "indexed": false, - "description": "Amount of stuff" - } - }, - "notice": "Emitted when transfer", - "details": "Transfer some stuff", - "custom:danger": "This event exposes private info" + "boop(uint256)": { + "stateMutability": "nonpayable", + "code": "function boop(uint256 bar) external nonpayable", + "inputs": { + "bar": { + "type": "uint256" + } + }, + "outputs": {}, + "notice": "Cool function bro", + "custom:requirement": "Check first requirementCheck second requirement" + }, + "boop(uint256,uint256)": { + "stateMutability": "nonpayable", + "code": "function boop(uint256 bar, uint256 bar2) external nonpayable", + "inputs": { + "bar": { + "type": "uint256" + }, + "bar2": { + "type": "uint256" } + }, + "outputs": {}, + "notice": "Alt cool function bro" }, - "errors": { - "Doh": { - "code": "error Doh(bool yay)", - "inputs": { - "yay": { - "type": "bool", - "description": "A bool" - } - }, - "notice": "Thrown when doh", - "details": "Bad doh error", - "custom:info": "Additional info" + "hello(bytes)": { + "stateMutability": "nonpayable", + "code": "function hello(bytes someCallData) external nonpayable", + "inputs": { + "someCallData": { + "type": "bytes", + "description": "hello tic tac toe" } + }, + "outputs": {} }, - "internalMethods": { - "_baap(uint256,address)": { - "code": "function _baap(uint256 bar, address aar) internal nonpayable", - "inputs": { - "bar": { - "type": "uint256", - "description": "Number of bar" - }, - "aar": { - "type": "address", - "description": "Address of aar" - } - }, - "outputs": {}, - "notice": "Baaps the yaps internally" + "set(tuple)": { + "stateMutability": "nonpayable", + "code": "function set(IBar.T t) external nonpayable", + "inputs": { + "t": { + "type": "IBar.T" } + }, + "outputs": {} }, - "path": "", - "title": "Bar contract", - "notice": "Manages the bar", - "details": "Blablou", - "author": "Primitive", - "custom:version": "v2.0.1", - "name": "Bar" -} \ No newline at end of file + "receive()": { + "stateMutability": "payable", + "code": "receive() external payable", + "inputs": {}, + "outputs": {}, + "details": "This is a `receive()` function", + "notice": "This is the notice of the `receive()` function", + "custom:info": "if sending native tokens with some graffiti, check the {`fallback()`} function documentation." + } + }, + "events": { + "Transfer": { + "code": "event Transfer(uint256 foo)", + "inputs": { + "foo": { + "type": "uint256", + "indexed": false, + "description": "Amount of stuff" + } + }, + "notice": "Emitted when transfer", + "details": "Transfer some stuff", + "custom:danger": "This event exposes private info" + } + }, + "errors": { + "Doh": { + "code": "error Doh(bool yay)", + "inputs": { + "yay": { + "type": "bool", + "description": "A bool" + } + }, + "notice": "Thrown when doh", + "details": "Bad doh error", + "custom:info": "Additional info" + } + }, + "internalMethods": { + "_baap(uint256,address)": { + "code": "function _baap(uint256 bar, address aar) internal nonpayable", + "inputs": { + "bar": { + "type": "uint256", + "description": "Number of bar" + }, + "aar": { + "type": "address", + "description": "Address of aar" + } + }, + "outputs": {}, + "notice": "Baaps the yaps internally" + } + }, + "path": "", + "title": "Bar contract", + "notice": "Manages the bar", + "details": "Blablou", + "author": "Primitive", + "custom:version": "v2.0.1", + "name": "Bar" +} diff --git a/examples/docs/contracts/Bar.md b/examples/docs/contracts/Bar.md index bcf6532..9bf389c 100644 --- a/examples/docs/contracts/Bar.md +++ b/examples/docs/contracts/Bar.md @@ -1,14 +1,14 @@ # Bar -*Primitive* +_Primitive_ > Bar contract Manages the bar -*Blablou* +_Blablou_ -**Version:** *v2.0.1* +**Version:** _v2.0.1_ ## Methods @@ -19,15 +19,12 @@ constructor(uint256 someNumber) ``` This is the notice of the constructor -*This is a constructor* - - - +_This is a constructor_ #### Parameters -| Name | Type | Description | -|---|---|---| +| Name | Type | Description | +| ---------- | ------- | -------------------------------- | | someNumber | uint256 | The description of the parameter | ### fallback @@ -37,21 +34,18 @@ fallback(bytes calldata fallbackParam) external nonpayable returns (bytes memory ``` This is the notice of the fallback -*This is a fallback* - - - +_This is a fallback_ #### Parameters -| Name | Type | Description | -|---|---|---| +| Name | Type | Description | +| ------------- | ----- | ---------------------------- | | fallbackParam | bytes | some details about the param | #### Returns -| Name | Type | Description | -|---|---|---| +| Name | Type | Description | +| -------- | ----- | ------------------------------------ | | testtest | bytes | result some details about the result | ### baap @@ -62,16 +56,12 @@ function baap(uint256 bar, address aar) external nonpayable Baaps the yaps - - - - #### Parameters -| Name | Type | Description | -|---|---|---| -| bar | uint256 | Number of bar | -| aar | address | Address of aar | +| Name | Type | Description | +| ---- | ------- | -------------- | +| bar | uint256 | Number of bar | +| aar | address | Address of aar | ### boop @@ -81,15 +71,13 @@ function boop(uint256 bar) external nonpayable Cool function bro -**Requirement:** *Check first requirementCheck second requirement* - - +**Requirement:** _Check first requirementCheck second requirement_ #### Parameters -| Name | Type | Description | -|---|---|---| -| bar | uint256 | undefined | +| Name | Type | Description | +| ---- | ------- | ----------- | +| bar | uint256 | undefined | ### boop @@ -99,16 +87,12 @@ function boop(uint256 bar, uint256 bar2) external nonpayable Alt cool function bro - - - - #### Parameters -| Name | Type | Description | -|---|---|---| -| bar | uint256 | undefined | -| bar2 | uint256 | undefined | +| Name | Type | Description | +| ---- | ------- | ----------- | +| bar | uint256 | undefined | +| bar2 | uint256 | undefined | ### hello @@ -116,16 +100,10 @@ Alt cool function bro function hello(bytes someCallData) external nonpayable ``` - - - - - - #### Parameters -| Name | Type | Description | -|---|---|---| +| Name | Type | Description | +| ------------ | ----- | ----------------- | | someCallData | bytes | hello tic tac toe | ### set @@ -134,17 +112,11 @@ function hello(bytes someCallData) external nonpayable function set(IBar.T t) external nonpayable ``` - - - - - - #### Parameters -| Name | Type | Description | -|---|---|---| -| t | IBar.T | undefined | +| Name | Type | Description | +| ---- | ------ | ----------- | +| t | IBar.T | undefined | ### receive @@ -153,17 +125,13 @@ receive() external payable ``` This is the notice of the `receive()` function -*This is a `receive()` function* - - -**Info:** *if sending native tokens with some graffiti, check the {`fallback()`} function documentation.* - - +_This is a `receive()` function_ +**Info:** _if sending native tokens with some graffiti, check the {`fallback()`} function documentation._ ## Internal Methods -### _baap +### \_baap ```solidity function _baap(uint256 bar, address aar) internal nonpayable @@ -171,18 +139,12 @@ function _baap(uint256 bar, address aar) internal nonpayable Baaps the yaps internally - - - - #### Parameters -| Name | Type | Description | -|---|---|---| -| bar | uint256 | Number of bar | -| aar | address | Address of aar | - - +| Name | Type | Description | +| ---- | ------- | -------------- | +| bar | uint256 | Number of bar | +| aar | address | Address of aar | ## Events @@ -193,19 +155,16 @@ event Transfer(uint256 foo) ``` Emitted when transfer -*Transfer some stuff* - -**Danger:** *This event exposes private info* +_Transfer some stuff_ +**Danger:** _This event exposes private info_ #### Parameters -| Name | Type | Description | -|---|---|---| +| Name | Type | Description | +| ---- | ------- | --------------- | | foo | uint256 | Amount of stuff | - - ## Errors ### Doh @@ -215,15 +174,12 @@ error Doh(bool yay) ``` Thrown when doh -*Bad doh error* +_Bad doh error_ - -**Info:** *Additional info* +**Info:** _Additional info_ #### Parameters | Name | Type | Description | -|---|---|---| -| yay | bool | A bool | - - +| ---- | ---- | ----------- | +| yay | bool | A bool | diff --git a/examples/docs/contracts/ExampleContract.json b/examples/docs/contracts/ExampleContract.json index 9ef090c..1046d89 100644 --- a/examples/docs/contracts/ExampleContract.json +++ b/examples/docs/contracts/ExampleContract.json @@ -1,141 +1,141 @@ { - "methods": { - "fallback()": { - "stateMutability": "nonpayable", - "code": "fallback(bytes calldata value) external nonpayable returns (bytes memory returnValue)", - "inputs": { - "value": { - "type": "bytes", - "description": "Some random value for the fallback" - } - }, - "outputs": { - "returnValue": { - "type": "bytes", - "description": "A nice return value post-computation" - } - }, - "notice": "A notice for the fallback", - "details": "A developer documentation comment for the fallback" - }, - "aNewFunc(uint256,bytes)": { - "stateMutability": "nonpayable", - "code": "function aNewFunc(uint256 somth, bytes anoth) external nonpayable", - "inputs": { - "somth": { - "type": "uint256", - "description": "Something funny" - }, - "anoth": { - "type": "bytes", - "description": "Another thing funny" - } - }, - "outputs": {}, - "notice": "New Func executed", - "details": "Some dev information about New Func" - }, - "anotherThing(uint256)": { - "stateMutability": "pure", - "code": "function anotherThing(uint256 num) external pure returns (uint256)", - "inputs": { - "num": { - "type": "uint256", - "description": "A random number" - } - }, - "outputs": { - "_0": { - "type": "uint256", - "description": "A random variable" - } - }, - "notice": "Does another thing when the function is called.", - "details": "More info about doing another thing when the function is called." - }, - "boop()": { - "stateMutability": "view", - "code": "function boop() external view returns (address)", - "inputs": {}, - "outputs": { - "_0": { - "type": "address" - } - }, - "notice": "Poorly documented function starting with weird spaces.", - "details": "New documentation, changing the interface" - }, - "doSomething(address,uint256)": { - "stateMutability": "nonpayable", - "code": "function doSomething(address a, uint256 b) external nonpayable returns (uint256 foo, uint256 bar)", - "inputs": { - "a": { - "type": "address", - "description": "Address to do something" - }, - "b": { - "type": "uint256", - "description": "Number to do something" - } - }, - "outputs": { - "foo": { - "type": "uint256", - "description": "First return variable" - }, - "bar": { - "type": "uint256", - "description": "Second return variable" - } - }, - "notice": "Does something when this function is called.", - "details": "More info about the doSomething, and this even works when the explanation is on two lines." + "methods": { + "fallback()": { + "stateMutability": "nonpayable", + "code": "fallback(bytes calldata value) external nonpayable returns (bytes memory returnValue)", + "inputs": { + "value": { + "type": "bytes", + "description": "Some random value for the fallback" + } + }, + "outputs": { + "returnValue": { + "type": "bytes", + "description": "A nice return value post-computation" + } + }, + "notice": "A notice for the fallback", + "details": "A developer documentation comment for the fallback" + }, + "aNewFunc(uint256,bytes)": { + "stateMutability": "nonpayable", + "code": "function aNewFunc(uint256 somth, bytes anoth) external nonpayable", + "inputs": { + "somth": { + "type": "uint256", + "description": "Something funny" }, - "pay()": { - "stateMutability": "payable", - "code": "function pay() external payable", - "inputs": {}, - "outputs": {}, - "notice": "A bad documented payable function." + "anoth": { + "type": "bytes", + "description": "Another thing funny" } + }, + "outputs": {}, + "notice": "New Func executed", + "details": "Some dev information about New Func" }, - "events": { - "DoSomething": { - "code": "event DoSomething(address indexed a, uint256 b)", - "inputs": { - "a": { - "type": "address", - "indexed": true, - "description": "Address of someone" - }, - "b": { - "type": "uint256", - "indexed": false, - "description": "A random number" - } - }, - "notice": "Emitted when the function doSomething is called.", - "details": "More info about the event can be added here." + "anotherThing(uint256)": { + "stateMutability": "pure", + "code": "function anotherThing(uint256 num) external pure returns (uint256)", + "inputs": { + "num": { + "type": "uint256", + "description": "A random number" } + }, + "outputs": { + "_0": { + "type": "uint256", + "description": "A random variable" + } + }, + "notice": "Does another thing when the function is called.", + "details": "More info about doing another thing when the function is called." }, - "errors": { - "RandomError": { - "code": "error RandomError(address expected, address actual)", - "inputs": { - "expected": { - "type": "address", - "description": "Expected address" - }, - "actual": { - "type": "address", - "description": "Actual address" - } - }, - "notice": "Thrown when an error happens.", - "details": "More info about the error." + "boop()": { + "stateMutability": "view", + "code": "function boop() external view returns (address)", + "inputs": {}, + "outputs": { + "_0": { + "type": "address" } + }, + "notice": "Poorly documented function starting with weird spaces.", + "details": "New documentation, changing the interface" }, - "internalMethods": {}, - "path": "", - "name": "ExampleContract" -} \ No newline at end of file + "doSomething(address,uint256)": { + "stateMutability": "nonpayable", + "code": "function doSomething(address a, uint256 b) external nonpayable returns (uint256 foo, uint256 bar)", + "inputs": { + "a": { + "type": "address", + "description": "Address to do something" + }, + "b": { + "type": "uint256", + "description": "Number to do something" + } + }, + "outputs": { + "foo": { + "type": "uint256", + "description": "First return variable" + }, + "bar": { + "type": "uint256", + "description": "Second return variable" + } + }, + "notice": "Does something when this function is called.", + "details": "More info about the doSomething, and this even works when the explanation is on two lines." + }, + "pay()": { + "stateMutability": "payable", + "code": "function pay() external payable", + "inputs": {}, + "outputs": {}, + "notice": "A bad documented payable function." + } + }, + "events": { + "DoSomething": { + "code": "event DoSomething(address indexed a, uint256 b)", + "inputs": { + "a": { + "type": "address", + "indexed": true, + "description": "Address of someone" + }, + "b": { + "type": "uint256", + "indexed": false, + "description": "A random number" + } + }, + "notice": "Emitted when the function doSomething is called.", + "details": "More info about the event can be added here." + } + }, + "errors": { + "RandomError": { + "code": "error RandomError(address expected, address actual)", + "inputs": { + "expected": { + "type": "address", + "description": "Expected address" + }, + "actual": { + "type": "address", + "description": "Actual address" + } + }, + "notice": "Thrown when an error happens.", + "details": "More info about the error." + } + }, + "internalMethods": {}, + "path": "", + "name": "ExampleContract" +} diff --git a/examples/docs/contracts/ExampleContract.md b/examples/docs/contracts/ExampleContract.md index b2b453f..2ddd488 100644 --- a/examples/docs/contracts/ExampleContract.md +++ b/examples/docs/contracts/ExampleContract.md @@ -1,15 +1,5 @@ # ExampleContract - - - - - - - - - - ## Methods ### fallback @@ -19,21 +9,18 @@ fallback(bytes calldata value) external nonpayable returns (bytes memory returnV ``` A notice for the fallback -*A developer documentation comment for the fallback* - - - +_A developer documentation comment for the fallback_ #### Parameters -| Name | Type | Description | -|---|---|---| +| Name | Type | Description | +| ----- | ----- | ---------------------------------- | | value | bytes | Some random value for the fallback | #### Returns -| Name | Type | Description | -|---|---|---| +| Name | Type | Description | +| ----------- | ----- | ------------------------------------ | | returnValue | bytes | A nice return value post-computation | ### aNewFunc @@ -43,17 +30,14 @@ function aNewFunc(uint256 somth, bytes anoth) external nonpayable ``` New Func executed -*Some dev information about New Func* - - - +_Some dev information about New Func_ #### Parameters -| Name | Type | Description | -|---|---|---| -| somth | uint256 | Something funny | -| anoth | bytes | Another thing funny | +| Name | Type | Description | +| ----- | ------- | ------------------- | +| somth | uint256 | Something funny | +| anoth | bytes | Another thing funny | ### anotherThing @@ -62,22 +46,19 @@ 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.* - - - +_More info about doing another thing when the function is called._ #### 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 | ### boop @@ -86,17 +67,13 @@ function boop() external view returns (address) ``` Poorly documented function starting with weird spaces. -*New documentation, changing the interface* - - - - +_New documentation, changing the interface_ #### Returns -| Name | Type | Description | -|---|---|---| -| _0 | address | undefined | +| Name | Type | Description | +| ---- | ------- | ----------- | +| \_0 | address | undefined | ### doSomething @@ -105,24 +82,21 @@ function doSomething(address a, uint256 b) external nonpayable returns (uint256 ``` Does something when this function is called. -*More info about the doSomething, and this even works when the explanation is on two lines.* - - - +_More info about the doSomething, and this even works when the explanation is on two lines._ #### Parameters -| Name | Type | Description | -|---|---|---| -| a | address | Address to do something | -| b | uint256 | Number to do something | +| Name | Type | Description | +| ---- | ------- | ----------------------- | +| a | address | Address to do something | +| b | uint256 | Number to do something | #### Returns -| Name | Type | Description | -|---|---|---| -| foo | uint256 | First return variable | -| bar | uint256 | Second return variable | +| Name | Type | Description | +| ---- | ------- | ---------------------- | +| foo | uint256 | First return variable | +| bar | uint256 | Second return variable | ### pay @@ -132,14 +106,6 @@ function pay() external payable A bad documented payable function. - - - - - - - - ## Events ### DoSomething @@ -149,19 +115,14 @@ event DoSomething(address indexed a, uint256 b) ``` Emitted when the function doSomething is called. -*More info about the event can be added here.* - - - +_More info about the event can be added here._ #### Parameters -| Name | Type | Description | -|---|---|---| +| Name | Type | Description | +| ----------- | ------- | ------------------ | | a `indexed` | address | Address of someone | -| b | uint256 | A random number | - - +| b | uint256 | A random number | ## Errors @@ -172,16 +133,11 @@ error RandomError(address expected, address actual) ``` Thrown when an error happens. -*More info about the error.* - - - +_More info about the error._ #### Parameters -| Name | Type | Description | -|---|---|---| +| Name | Type | Description | +| -------- | ------- | ---------------- | | expected | address | Expected address | -| actual | address | Actual address | - - +| actual | address | Actual address | diff --git a/examples/docs/contracts/FallbackContract.json b/examples/docs/contracts/FallbackContract.json index 27bbcfc..2aa4e3c 100644 --- a/examples/docs/contracts/FallbackContract.json +++ b/examples/docs/contracts/FallbackContract.json @@ -1,27 +1,27 @@ { - "methods": { - "fallback()": { - "stateMutability": "nonpayable", - "code": "fallback(bytes calldata value) external nonpayable returns (bytes memory returnValue)", - "inputs": { - "value": { - "type": "bytes", - "description": "Some random value for the fallback" - } - }, - "outputs": { - "returnValue": { - "type": "bytes", - "description": "A nice return value post-computation" - } - }, - "notice": "A notice for the fallback", - "details": "A developer documentation comment for the fallback" + "methods": { + "fallback()": { + "stateMutability": "nonpayable", + "code": "fallback(bytes calldata value) external nonpayable returns (bytes memory returnValue)", + "inputs": { + "value": { + "type": "bytes", + "description": "Some random value for the fallback" } - }, - "events": {}, - "errors": {}, - "internalMethods": {}, - "path": "", - "name": "FallbackContract" -} \ No newline at end of file + }, + "outputs": { + "returnValue": { + "type": "bytes", + "description": "A nice return value post-computation" + } + }, + "notice": "A notice for the fallback", + "details": "A developer documentation comment for the fallback" + } + }, + "events": {}, + "errors": {}, + "internalMethods": {}, + "path": "", + "name": "FallbackContract" +} diff --git a/examples/docs/contracts/FallbackContract.md b/examples/docs/contracts/FallbackContract.md index 32130be..3aedce8 100644 --- a/examples/docs/contracts/FallbackContract.md +++ b/examples/docs/contracts/FallbackContract.md @@ -1,15 +1,5 @@ # FallbackContract - - - - - - - - - - ## Methods ### fallback @@ -19,24 +9,16 @@ fallback(bytes calldata value) external nonpayable returns (bytes memory returnV ``` A notice for the fallback -*A developer documentation comment for the fallback* - - - +_A developer documentation comment for the fallback_ #### Parameters -| Name | Type | Description | -|---|---|---| +| Name | Type | Description | +| ----- | ----- | ---------------------------------- | | value | bytes | Some random value for the fallback | #### Returns -| Name | Type | Description | -|---|---|---| +| Name | Type | Description | +| ----------- | ----- | ------------------------------------ | | returnValue | bytes | A nice return value post-computation | - - - - - diff --git a/examples/docs/contracts/IBar.json b/examples/docs/contracts/IBar.json index 71a9fd0..585c45a 100644 --- a/examples/docs/contracts/IBar.json +++ b/examples/docs/contracts/IBar.json @@ -1,72 +1,72 @@ { - "methods": { - "boop(uint256)": { - "stateMutability": "nonpayable", - "code": "function boop(uint256 bar) external nonpayable", - "inputs": { - "bar": { - "type": "uint256" - } - }, - "outputs": {} - }, - "set(tuple)": { - "stateMutability": "nonpayable", - "code": "function set(IBar.T t) external nonpayable", - "inputs": { - "t": { - "type": "IBar.T" - } - }, - "outputs": {} + "methods": { + "boop(uint256)": { + "stateMutability": "nonpayable", + "code": "function boop(uint256 bar) external nonpayable", + "inputs": { + "bar": { + "type": "uint256" } + }, + "outputs": {} }, - "events": { - "Transfer": { - "code": "event Transfer(uint256 foo)", - "inputs": { - "foo": { - "type": "uint256", - "indexed": false, - "description": "Amount of stuff" - } - }, - "notice": "Emitted when transfer", - "details": "Transfer some stuff", - "custom:danger": "This event exposes private info" + "set(tuple)": { + "stateMutability": "nonpayable", + "code": "function set(IBar.T t) external nonpayable", + "inputs": { + "t": { + "type": "IBar.T" } - }, - "errors": { - "Doh": { - "code": "error Doh(bool yay)", - "inputs": { - "yay": { - "type": "bool", - "description": "A bool" - } - }, - "notice": "Thrown when doh", - "details": "Bad doh error", - "custom:info": "Additional info" + }, + "outputs": {} + } + }, + "events": { + "Transfer": { + "code": "event Transfer(uint256 foo)", + "inputs": { + "foo": { + "type": "uint256", + "indexed": false, + "description": "Amount of stuff" } - }, - "internalMethods": { - "_baap(uint256,address)": { - "code": "function _baap(uint256 bar, address aar) internal nonpayable", - "inputs": { - "bar": { - "type": "uint256", - "description": "Number of bar" - }, - "aar": { - "type": "address", - "description": "Address of aar" - } - }, - "outputs": {}, - "notice": "Baaps the yaps internally" + }, + "notice": "Emitted when transfer", + "details": "Transfer some stuff", + "custom:danger": "This event exposes private info" + } + }, + "errors": { + "Doh": { + "code": "error Doh(bool yay)", + "inputs": { + "yay": { + "type": "bool", + "description": "A bool" } - }, - "path": "", - "name": "IBar" -} \ No newline at end of file + }, + "notice": "Thrown when doh", + "details": "Bad doh error", + "custom:info": "Additional info" + } + }, + "internalMethods": { + "_baap(uint256,address)": { + "code": "function _baap(uint256 bar, address aar) internal nonpayable", + "inputs": { + "bar": { + "type": "uint256", + "description": "Number of bar" + }, + "aar": { + "type": "address", + "description": "Address of aar" + } + }, + "outputs": {}, + "notice": "Baaps the yaps internally" + } + }, + "path": "", + "name": "IBar" +} diff --git a/examples/docs/contracts/IBar.md b/examples/docs/contracts/IBar.md index 812bfe3..80b6807 100644 --- a/examples/docs/contracts/IBar.md +++ b/examples/docs/contracts/IBar.md @@ -1,15 +1,5 @@ # IBar - - - - - - - - - - ## Methods ### boop @@ -18,17 +8,11 @@ function boop(uint256 bar) external nonpayable ``` - - - - - - #### Parameters -| Name | Type | Description | -|---|---|---| -| bar | uint256 | undefined | +| Name | Type | Description | +| ---- | ------- | ----------- | +| bar | uint256 | undefined | ### set @@ -36,23 +20,15 @@ function boop(uint256 bar) external nonpayable function set(IBar.T t) external nonpayable ``` - - - - - - #### Parameters -| Name | Type | Description | -|---|---|---| -| t | IBar.T | undefined | - - +| Name | Type | Description | +| ---- | ------ | ----------- | +| t | IBar.T | undefined | ## Internal Methods -### _baap +### \_baap ```solidity function _baap(uint256 bar, address aar) internal nonpayable @@ -60,18 +36,12 @@ function _baap(uint256 bar, address aar) internal nonpayable Baaps the yaps internally - - - - #### Parameters -| Name | Type | Description | -|---|---|---| -| bar | uint256 | Number of bar | -| aar | address | Address of aar | - - +| Name | Type | Description | +| ---- | ------- | -------------- | +| bar | uint256 | Number of bar | +| aar | address | Address of aar | ## Events @@ -82,19 +52,16 @@ event Transfer(uint256 foo) ``` Emitted when transfer -*Transfer some stuff* - -**Danger:** *This event exposes private info* +_Transfer some stuff_ +**Danger:** _This event exposes private info_ #### Parameters -| Name | Type | Description | -|---|---|---| +| Name | Type | Description | +| ---- | ------- | --------------- | | foo | uint256 | Amount of stuff | - - ## Errors ### Doh @@ -104,15 +71,12 @@ error Doh(bool yay) ``` Thrown when doh -*Bad doh error* - +_Bad doh error_ -**Info:** *Additional info* +**Info:** _Additional info_ #### Parameters | Name | Type | Description | -|---|---|---| -| yay | bool | A bool | - - +| ---- | ---- | ----------- | +| yay | bool | A bool | diff --git a/examples/docs/contracts/IExampleContract.json b/examples/docs/contracts/IExampleContract.json index 0be382c..ccedbb5 100644 --- a/examples/docs/contracts/IExampleContract.json +++ b/examples/docs/contracts/IExampleContract.json @@ -1,110 +1,110 @@ { - "methods": { - "anotherThing(uint256)": { - "stateMutability": "pure", - "code": "function anotherThing(uint256 num) external pure returns (uint256)", - "inputs": { - "num": { - "type": "uint256", - "description": "A random number" - } - }, - "outputs": { - "_0": { - "type": "uint256", - "description": "A random variable" - } - }, - "notice": "Does another thing when the function is called.", - "details": "More info about doing another thing when the function is called." - }, - "boop()": { - "stateMutability": "view", - "code": "function boop() external view returns (address)", - "inputs": {}, - "outputs": { - "_0": { - "type": "address" - } - }, - "notice": "Poorly documented function starting with weird spaces.", - "details": "Initital dev documentation" - }, - "doSomething(address,uint256)": { - "stateMutability": "nonpayable", - "code": "function doSomething(address a, uint256 b) external nonpayable returns (uint256 foo, uint256 bar)", - "inputs": { - "a": { - "type": "address", - "description": "Address to do something" - }, - "b": { - "type": "uint256", - "description": "Number to do something" - } - }, - "outputs": { - "foo": { - "type": "uint256", - "description": "First return variable" - }, - "bar": { - "type": "uint256", - "description": "Second return variable" - } - }, - "notice": "Does something when this function is called.", - "details": "More info about the doSomething, and this even works when the explanation is on two lines." - }, - "pay()": { - "stateMutability": "payable", - "code": "function pay() external payable", - "inputs": {}, - "outputs": {}, - "notice": "A bad documented payable function." + "methods": { + "anotherThing(uint256)": { + "stateMutability": "pure", + "code": "function anotherThing(uint256 num) external pure returns (uint256)", + "inputs": { + "num": { + "type": "uint256", + "description": "A random number" } + }, + "outputs": { + "_0": { + "type": "uint256", + "description": "A random variable" + } + }, + "notice": "Does another thing when the function is called.", + "details": "More info about doing another thing when the function is called." }, - "events": { - "DoSomething": { - "code": "event DoSomething(address indexed a, uint256 b)", - "inputs": { - "a": { - "type": "address", - "indexed": true, - "description": "Address of someone" - }, - "b": { - "type": "uint256", - "indexed": false, - "description": "A random number" - } - }, - "notice": "Emitted when the function doSomething is called.", - "details": "More info about the event can be added here." + "boop()": { + "stateMutability": "view", + "code": "function boop() external view returns (address)", + "inputs": {}, + "outputs": { + "_0": { + "type": "address" } + }, + "notice": "Poorly documented function starting with weird spaces.", + "details": "Initital dev documentation" }, - "errors": { - "RandomError": { - "code": "error RandomError(address expected, address actual)", - "inputs": { - "expected": { - "type": "address", - "description": "Expected address" - }, - "actual": { - "type": "address", - "description": "Actual address" - } - }, - "notice": "Thrown when an error happens.", - "details": "More info about the error." + "doSomething(address,uint256)": { + "stateMutability": "nonpayable", + "code": "function doSomething(address a, uint256 b) external nonpayable returns (uint256 foo, uint256 bar)", + "inputs": { + "a": { + "type": "address", + "description": "Address to do something" + }, + "b": { + "type": "uint256", + "description": "Number to do something" } + }, + "outputs": { + "foo": { + "type": "uint256", + "description": "First return variable" + }, + "bar": { + "type": "uint256", + "description": "Second return variable" + } + }, + "notice": "Does something when this function is called.", + "details": "More info about the doSomething, and this even works when the explanation is on two lines." }, - "internalMethods": {}, - "path": "", - "title": "Interface of our ExampleContract", - "notice": "Put a simple description of the contract here.", - "details": "And then a more complicated and tech oriented description of the contract there.", - "author": "0xAn0n", - "name": "IExampleContract" -} \ No newline at end of file + "pay()": { + "stateMutability": "payable", + "code": "function pay() external payable", + "inputs": {}, + "outputs": {}, + "notice": "A bad documented payable function." + } + }, + "events": { + "DoSomething": { + "code": "event DoSomething(address indexed a, uint256 b)", + "inputs": { + "a": { + "type": "address", + "indexed": true, + "description": "Address of someone" + }, + "b": { + "type": "uint256", + "indexed": false, + "description": "A random number" + } + }, + "notice": "Emitted when the function doSomething is called.", + "details": "More info about the event can be added here." + } + }, + "errors": { + "RandomError": { + "code": "error RandomError(address expected, address actual)", + "inputs": { + "expected": { + "type": "address", + "description": "Expected address" + }, + "actual": { + "type": "address", + "description": "Actual address" + } + }, + "notice": "Thrown when an error happens.", + "details": "More info about the error." + } + }, + "internalMethods": {}, + "path": "", + "title": "Interface of our ExampleContract", + "notice": "Put a simple description of the contract here.", + "details": "And then a more complicated and tech oriented description of the contract there.", + "author": "0xAn0n", + "name": "IExampleContract" +} diff --git a/examples/docs/contracts/IExampleContract.md b/examples/docs/contracts/IExampleContract.md index 620fa36..1db00da 100644 --- a/examples/docs/contracts/IExampleContract.md +++ b/examples/docs/contracts/IExampleContract.md @@ -1,14 +1,12 @@ # IExampleContract -*0xAn0n* +_0xAn0n_ > Interface of our ExampleContract Put a simple description of the contract here. -*And then a more complicated and tech oriented description of the contract there.* - - +_And then a more complicated and tech oriented description of the contract there._ ## Methods @@ -19,22 +17,19 @@ 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.* - - - +_More info about doing another thing when the function is called._ #### 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 | ### boop @@ -43,17 +38,13 @@ function boop() external view returns (address) ``` Poorly documented function starting with weird spaces. -*Initital dev documentation* - - - - +_Initital dev documentation_ #### Returns -| Name | Type | Description | -|---|---|---| -| _0 | address | undefined | +| Name | Type | Description | +| ---- | ------- | ----------- | +| \_0 | address | undefined | ### doSomething @@ -62,24 +53,21 @@ function doSomething(address a, uint256 b) external nonpayable returns (uint256 ``` Does something when this function is called. -*More info about the doSomething, and this even works when the explanation is on two lines.* - - - +_More info about the doSomething, and this even works when the explanation is on two lines._ #### Parameters -| Name | Type | Description | -|---|---|---| -| a | address | Address to do something | -| b | uint256 | Number to do something | +| Name | Type | Description | +| ---- | ------- | ----------------------- | +| a | address | Address to do something | +| b | uint256 | Number to do something | #### Returns -| Name | Type | Description | -|---|---|---| -| foo | uint256 | First return variable | -| bar | uint256 | Second return variable | +| Name | Type | Description | +| ---- | ------- | ---------------------- | +| foo | uint256 | First return variable | +| bar | uint256 | Second return variable | ### pay @@ -89,14 +77,6 @@ function pay() external payable A bad documented payable function. - - - - - - - - ## Events ### DoSomething @@ -106,19 +86,14 @@ event DoSomething(address indexed a, uint256 b) ``` Emitted when the function doSomething is called. -*More info about the event can be added here.* - - - +_More info about the event can be added here._ #### Parameters -| Name | Type | Description | -|---|---|---| +| Name | Type | Description | +| ----------- | ------- | ------------------ | | a `indexed` | address | Address of someone | -| b | uint256 | A random number | - - +| b | uint256 | A random number | ## Errors @@ -129,16 +104,11 @@ error RandomError(address expected, address actual) ``` Thrown when an error happens. -*More info about the error.* - - - +_More info about the error._ #### Parameters -| Name | Type | Description | -|---|---|---| +| Name | Type | Description | +| -------- | ------- | ---------------- | | expected | address | Expected address | -| actual | address | Actual address | - - +| actual | address | Actual address | diff --git a/examples/docs/contracts/SomeOtherLibrary/SomeOtherLibrary.json b/examples/docs/contracts/SomeOtherLibrary/SomeOtherLibrary.json index 2e4d43d..44c8256 100644 --- a/examples/docs/contracts/SomeOtherLibrary/SomeOtherLibrary.json +++ b/examples/docs/contracts/SomeOtherLibrary/SomeOtherLibrary.json @@ -1,88 +1,88 @@ { - "methods": {}, - "events": {}, - "errors": { - "WhateverError": { - "code": "WhateverError(bytes16)", - "notice": "", - "details": "", - "inputs": { - "somethingElse": { - "type": "bytes16", - "description": "" - } - } - }, - "ThirdError": { - "code": "ThirdError(bytes4,uint256)", - "notice": "", - "details": "this is the third error", - "inputs": { - "functionSelector": { - "type": "bytes4", - "description": "fucntionMask This is a function mask" - }, - "fucntionMask": { - "type": "uint256", - "description": "This is a function mask" - } - }, - "custom:danger": "Be careful, this Error is dangerous" - }, - "SomeOtherError": { - "code": "SomeOtherError()", - "notice": "Some Other Error fired!!!!", - "details": "", - "inputs": {} - }, - "SomeError": { - "code": "SomeError(bytes32)", - "notice": "Invalid hash", - "details": "Reverts when hash has already been discovered", - "inputs": { - "invalidHash": { - "type": "bytes32", - "description": "Invalid hash." - } - } + "methods": {}, + "events": {}, + "errors": { + "SomeError": { + "code": "SomeError(bytes32)", + "notice": "Invalid hash", + "details": "Reverts when hash has already been discovered", + "inputs": { + "invalidHash": { + "type": "bytes32", + "description": "Invalid hash." } + } }, - "internalMethods": { - "someFunction(string)": { - "code": "function someFunction(string someText) internal pure returns (bytes32)", - "inputs": { - "someText": { - "type": "string", - "description": "Any text that you want to hash." - } - }, - "outputs": { - "_0": { - "type": "bytes32", - "description": "The hash that was sent as a parameter." - } - }, - "details": "This function uses `keccak256(..)` to hash text.", - "notice": "Hash returned." + "SomeOtherError": { + "code": "SomeOtherError()", + "notice": "Some Other Error fired!!!!", + "details": "", + "inputs": {} + }, + "ThirdError": { + "code": "ThirdError(bytes4,uint256)", + "notice": "", + "details": "This is the third error.\n The error does the following things:\n - Shows you the `functionSelector`.\n - Shows you the `functionMask`.\n - Shows you an error", + "inputs": { + "functionSelector": { + "type": "bytes4", + "description": "functionMask This is a function mask" }, - "someOtherFunction(string)": { - "code": "function someOtherFunction(string someText) internal pure returns (bytes32 hash)", - "inputs": { - "someText": { - "type": "string", - "description": "Any text that you want to hash." - } - }, - "outputs": { - "hash": { - "type": "bytes32", - "description": "The hash that was sent as a parameter." - } - }, - "details": "This function uses `sha256(..)` to hash text.", - "notice": "Hash returned." + "functionMask": { + "type": "uint256", + "description": "This is a function mask" + } + }, + "custom:danger": "Be careful, this Error is dangerous" + }, + "ErrorWithoutNatspec": { + "code": "ErrorWithoutNatspec(bytes16)", + "notice": "", + "details": "", + "inputs": { + "somethingElse": { + "type": "bytes16", + "description": "" + } + } + } + }, + "internalMethods": { + "someFunction(string)": { + "code": "function someFunction(string someText) internal pure returns (bytes32)", + "inputs": { + "someText": { + "type": "string", + "description": "Any text that you want to hash." + } + }, + "outputs": { + "_0": { + "type": "bytes32", + "description": "The hash that was sent as a parameter." } + }, + "details": "This function uses `keccak256(..)` to hash text.", + "notice": "Hash returned." }, - "path": "SomeOtherLibrary", - "name": "SomeOtherLibrary" -} \ No newline at end of file + "someOtherFunction(string)": { + "code": "function someOtherFunction(string someText) internal pure returns (bytes32 hash)", + "inputs": { + "someText": { + "type": "string", + "description": "Any text that you want to hash." + } + }, + "outputs": { + "hash": { + "type": "bytes32", + "description": "The hash that was sent as a parameter." + } + }, + "details": "This function uses `sha256(..)` to hash text.", + "notice": "Hash returned." + } + }, + "path": "SomeOtherLibrary", + "name": "SomeOtherLibrary" +} diff --git a/examples/docs/contracts/SomeOtherLibrary/SomeOtherLibrary.md b/examples/docs/contracts/SomeOtherLibrary/SomeOtherLibrary.md index 061e896..da96df7 100644 --- a/examples/docs/contracts/SomeOtherLibrary/SomeOtherLibrary.md +++ b/examples/docs/contracts/SomeOtherLibrary/SomeOtherLibrary.md @@ -1,16 +1,5 @@ # SomeOtherLibrary - - - - - - - - - - - ## Internal Methods ### someFunction @@ -20,22 +9,19 @@ function someFunction(string someText) internal pure returns (bytes32) ``` Hash returned. -*This function uses `keccak256(..)` to hash text.* - - - +_This function uses `keccak256(..)` to hash text._ #### Parameters -| Name | Type | Description | -|---|---|---| +| Name | Type | Description | +| -------- | ------ | ------------------------------- | | someText | string | Any text that you want to hash. | #### Returns -| Name | Type | Description | -|---|---|---| -| _0 | bytes32 | The hash that was sent as a parameter. | +| Name | Type | Description | +| ---- | ------- | -------------------------------------- | +| \_0 | bytes32 | The hash that was sent as a parameter. | ### someOtherFunction @@ -44,94 +30,75 @@ function someOtherFunction(string someText) internal pure returns (bytes32 hash) ``` Hash returned. -*This function uses `sha256(..)` to hash text.* - - - +_This function uses `sha256(..)` to hash text._ #### Parameters -| Name | Type | Description | -|---|---|---| +| Name | Type | Description | +| -------- | ------ | ------------------------------- | | someText | string | Any text that you want to hash. | #### Returns -| Name | Type | Description | -|---|---|---| +| Name | Type | Description | +| ---- | ------- | -------------------------------------- | | hash | bytes32 | The hash that was sent as a parameter. | - - - ## Errors -### WhateverError +### SomeError ```solidity -WhateverError(bytes16) +SomeError(bytes32) ``` - - - - - +Invalid hash +_Reverts when hash has already been discovered_ #### Parameters -| Name | Type | Description | -|---|---|---| -| somethingElse | bytes16 | | +| Name | Type | Description | +| ----------- | ------- | ------------- | +| invalidHash | bytes32 | Invalid hash. | -### ThirdError +### SomeOtherError ```solidity -ThirdError(bytes4,uint256) +SomeOtherError() ``` +Some Other Error fired!!!! -*this is the third error* - -**Danger:** *Be careful, this Error is dangerous* - - -#### Parameters - -| Name | Type | Description | -|---|---|---| -| functionSelector | bytes4 | fucntionMask This is a function mask | -| fucntionMask | uint256 | This is a function mask | - -### SomeOtherError +### ThirdError ```solidity -SomeOtherError() +ThirdError(bytes4,uint256) ``` -Some Other Error fired!!!! +\*This is the third error. +The error does the following things: +- Shows you the `functionSelector`. +- Shows you the `functionMask`. +- Shows you an error\* +**Danger:** _Be careful, this Error is dangerous_ +#### Parameters +| Name | Type | Description | +| ---------------- | ------- | ------------------------------------ | +| functionSelector | bytes4 | functionMask This is a function mask | +| functionMask | uint256 | This is a function mask | - -### SomeError +### ErrorWithoutNatspec ```solidity -SomeError(bytes32) +ErrorWithoutNatspec(bytes16) ``` -Invalid hash -*Reverts when hash has already been discovered* - - - - #### Parameters -| Name | Type | Description | -|---|---|---| -| invalidHash | bytes32 | Invalid hash. | - - +| Name | Type | Description | +| ------------- | ------- | ----------- | +| somethingElse | bytes16 | | diff --git a/examples/docs/contracts/subfolder/AnotherContract.json b/examples/docs/contracts/subfolder/AnotherContract.json index 1ea1eee..4a4fccf 100644 --- a/examples/docs/contracts/subfolder/AnotherContract.json +++ b/examples/docs/contracts/subfolder/AnotherContract.json @@ -1,26 +1,26 @@ { - "methods": { - "tip(uint256,address)": { - "stateMutability": "nonpayable", - "code": "function tip(uint256 much, address mop) external nonpayable", - "inputs": { - "much": { - "type": "uint256", - "description": "How much" - }, - "mop": { - "type": "address", - "description": "No idea what this is" - } - }, - "outputs": {}, - "notice": "A strange function", - "details": "Someone wrote this weird function..." + "methods": { + "tip(uint256,address)": { + "stateMutability": "nonpayable", + "code": "function tip(uint256 much, address mop) external nonpayable", + "inputs": { + "much": { + "type": "uint256", + "description": "How much" + }, + "mop": { + "type": "address", + "description": "No idea what this is" } - }, - "events": {}, - "errors": {}, - "internalMethods": {}, - "path": "subfolder", - "name": "AnotherContract" -} \ No newline at end of file + }, + "outputs": {}, + "notice": "A strange function", + "details": "Someone wrote this weird function..." + } + }, + "events": {}, + "errors": {}, + "internalMethods": {}, + "path": "subfolder", + "name": "AnotherContract" +} diff --git a/examples/docs/contracts/subfolder/AnotherContract.md b/examples/docs/contracts/subfolder/AnotherContract.md index f27060f..8ba0060 100644 --- a/examples/docs/contracts/subfolder/AnotherContract.md +++ b/examples/docs/contracts/subfolder/AnotherContract.md @@ -1,15 +1,5 @@ # AnotherContract - - - - - - - - - - ## Methods ### tip @@ -19,19 +9,11 @@ function tip(uint256 much, address mop) external nonpayable ``` A strange function -*Someone wrote this weird function...* - - - +_Someone wrote this weird function..._ #### Parameters -| Name | Type | Description | -|---|---|---| -| much | uint256 | How much | -| mop | address | No idea what this is | - - - - - +| Name | Type | Description | +| ---- | ------- | -------------------- | +| much | uint256 | How much | +| mop | address | No idea what this is | diff --git a/examples/docs/libraries/Foo.json b/examples/docs/libraries/Foo.json index b7e9188..3a28dde 100644 --- a/examples/docs/libraries/Foo.json +++ b/examples/docs/libraries/Foo.json @@ -1,27 +1,27 @@ { - "methods": { - "nonces(address)": { - "stateMutability": "view", - "code": "function nonces(address) external view returns (uint256)", - "inputs": { - "_0": { - "type": "address", - "description": "Address to inspect" - } - }, - "outputs": { - "_0": { - "type": "uint256", - "description": "Current nonce of the address" - } - }, - "notice": "Returns the nonce of an address", - "details": "Nonces much" + "methods": { + "nonces(address)": { + "stateMutability": "view", + "code": "function nonces(address) external view returns (uint256)", + "inputs": { + "_0": { + "type": "address", + "description": "Address to inspect" } - }, - "events": {}, - "errors": {}, - "internalMethods": {}, - "path": "", - "name": "Foo" -} \ No newline at end of file + }, + "outputs": { + "_0": { + "type": "uint256", + "description": "Current nonce of the address" + } + }, + "notice": "Returns the nonce of an address", + "details": "Nonces much" + } + }, + "events": {}, + "errors": {}, + "internalMethods": {}, + "path": "", + "name": "Foo" +} diff --git a/examples/docs/libraries/Foo.md b/examples/docs/libraries/Foo.md index 1583c4e..0cefb2c 100644 --- a/examples/docs/libraries/Foo.md +++ b/examples/docs/libraries/Foo.md @@ -1,15 +1,5 @@ # Foo - - - - - - - - - - ## Methods ### nonces @@ -19,24 +9,16 @@ function nonces(address) external view returns (uint256) ``` Returns the nonce of an address -*Nonces much* - - - +_Nonces much_ #### Parameters -| Name | Type | Description | -|---|---|---| -| _0 | address | Address to inspect | +| Name | Type | Description | +| ---- | ------- | ------------------ | +| \_0 | address | Address to inspect | #### Returns -| Name | Type | Description | -|---|---|---| -| _0 | uint256 | Current nonce of the address | - - - - - +| Name | Type | Description | +| ---- | ------- | ---------------------------- | +| \_0 | uint256 | Current nonce of the address | diff --git a/examples/docs/libraries/IFoo.json b/examples/docs/libraries/IFoo.json index d98c81e..e81fb80 100644 --- a/examples/docs/libraries/IFoo.json +++ b/examples/docs/libraries/IFoo.json @@ -1,27 +1,27 @@ { - "methods": { - "nonces(address)": { - "stateMutability": "view", - "code": "function nonces(address _0) external view returns (uint256)", - "inputs": { - "_0": { - "type": "address", - "description": "Address to inspect" - } - }, - "outputs": { - "_0": { - "type": "uint256", - "description": "Current nonce of the address" - } - }, - "notice": "Returns the nonce of an address", - "details": "Nonces much" + "methods": { + "nonces(address)": { + "stateMutability": "view", + "code": "function nonces(address _0) external view returns (uint256)", + "inputs": { + "_0": { + "type": "address", + "description": "Address to inspect" } - }, - "events": {}, - "errors": {}, - "internalMethods": {}, - "path": "", - "name": "IFoo" -} \ No newline at end of file + }, + "outputs": { + "_0": { + "type": "uint256", + "description": "Current nonce of the address" + } + }, + "notice": "Returns the nonce of an address", + "details": "Nonces much" + } + }, + "events": {}, + "errors": {}, + "internalMethods": {}, + "path": "", + "name": "IFoo" +} diff --git a/examples/docs/libraries/IFoo.md b/examples/docs/libraries/IFoo.md index 8dc8bd1..d7b80e9 100644 --- a/examples/docs/libraries/IFoo.md +++ b/examples/docs/libraries/IFoo.md @@ -1,15 +1,5 @@ # IFoo - - - - - - - - - - ## Methods ### nonces @@ -19,24 +9,16 @@ function nonces(address _0) external view returns (uint256) ``` Returns the nonce of an address -*Nonces much* - - - +_Nonces much_ #### Parameters -| Name | Type | Description | -|---|---|---| -| _0 | address | Address to inspect | +| Name | Type | Description | +| ---- | ------- | ------------------ | +| \_0 | address | Address to inspect | #### Returns -| Name | Type | Description | -|---|---|---| -| _0 | uint256 | Current nonce of the address | - - - - - +| Name | Type | Description | +| ---- | ------- | ---------------------------- | +| \_0 | uint256 | Current nonce of the address | diff --git a/src/index.ts b/src/index.ts index e98151e..daf7b5b 100644 --- a/src/index.ts +++ b/src/index.ts @@ -6,7 +6,7 @@ import { TASK_COMPILE } from 'hardhat/builtin-tasks/task-names'; import { HardhatConfig, HardhatRuntimeEnvironment, HardhatUserConfig } from 'hardhat/types'; import * as Sqrl from 'squirrelly'; -import { CompilerOutputContractWithDocumentation, CustomTag, Doc, Param } from './dodocTypes'; +import { CompilerOutputContractWithDocumentation, Doc, Error, Param } from './dodocTypes'; import { decodeAbi } from './abiDecoder'; import './type-extensions'; import { clearWhitespaces } from './utils'; @@ -124,7 +124,7 @@ async function generateDocumentation(hre: HardhatRuntimeEnvironment): Promise 0) { if (doc.errors[errorName]) { doc.errors[errorName][`custom:${strippedValue}`] = error[`custom:${strippedValue}`]; @@ -148,7 +148,7 @@ async function generateDocumentation(hre: HardhatRuntimeEnvironment): Promise 0) { if (doc.events[eventName]) { doc.events[eventName][`custom:${strippedValue}`] = event[`custom:${strippedValue}`]; @@ -436,18 +436,19 @@ async function generateDocumentation(hre: HardhatRuntimeEnvironment): Promise { - let j = contractIndex; - while (AST[j].nodeType !== 'PragmaDirective') { - if (AST[j].nodeType === 'ErrorDefinition') { - const errorName: string = AST[j].name; - const errorDocs: { tag?: string; description?: string }[] = AST[j].documentation?.text + const parseNatspecOfErrorsFromAST = async () => { + AST.forEach((astNode: any) => { + if (astNode.nodeType === 'ErrorDefinition') { + const errorName: string = astNode.name; + + const errorDocs: { tag?: string; description?: string }[] = astNode.documentation?.text .split('@') .map((elem: string) => ({ tag: elem.substring(0, elem.indexOf(' ')), description: elem.substring(elem.indexOf(' ') + 1), })); - const errorParams: { paramType: string; paramName: string }[] = AST[j].parameters.parameters.map( + + const errorParams: { paramType: string; paramName: string }[] = astNode.parameters.parameters.map( (elem: any) => ({ paramType: elem.typeName.name, paramName: elem.name, @@ -471,10 +472,8 @@ async function generateDocumentation(hre: HardhatRuntimeEnvironment): Promise { let elemDescription: string = ''; errorDocs?.forEach((docsElem: { tag?: string; description?: string }) => { - if (docsElem.tag === 'param') { - if (docsElem.description) { - elemDescription = docsElem.description.replace(`${elem.paramName}`, ''); - } + if (docsElem.tag === 'param' && docsElem.description) { + elemDescription = docsElem.description.replace(`${elem.paramName}`, ''); } }); @@ -484,34 +483,25 @@ async function generateDocumentation(hre: HardhatRuntimeEnvironment): Promise]: string; - } = { + const error: Error = { code, notice: clearWhitespaces(notice?.description ? notice.description : ''), details: clearWhitespaces(dev?.description ? dev.description : ''), inputs, }; + custom?.forEach((elem) => { if (elem.tag) { - const strippedValue = elem.tag.substring(7); - if (strippedValue.length > 0) { - if (elem.description) { - error[`custom:${strippedValue}`] = clearWhitespaces(elem.description); - } + const strippedValue = elem.tag.replace('custom:', ''); + if (strippedValue.length > 0 && elem.description) { + error[`custom:${strippedValue}`] = clearWhitespaces(elem.description); } } }); doc.errors[errorName] = error; } - - j -= 1; - } + }); }; const libraryNodes: any[] = []; @@ -522,9 +512,9 @@ async function generateDocumentation(hre: HardhatRuntimeEnvironment): Promise { + libraryNodes.forEach(({ node }) => { parseNatspecOfInternalFunctionsFromAST(node); - parseNatspecOfErrorsFromAST(index); + parseNatspecOfErrorsFromAST(); }); // contract have inheritance, so we need to search for all the internal functions @@ -584,7 +574,7 @@ async function generateDocumentation(hre: HardhatRuntimeEnvironment): Promise 0) { if (doc.methods[methodSig]) { doc.methods[methodSig][`custom:${strippedValue}`] = method[`custom:${strippedValue}`]; @@ -625,7 +615,7 @@ async function generateDocumentation(hre: HardhatRuntimeEnvironment): Promise 0) { doc[`custom:${strippedValue}`] = info.devdoc[`custom:${strippedValue}`]; } diff --git a/src/utils.ts b/src/utils.ts index 806fe58..d2e4963 100644 --- a/src/utils.ts +++ b/src/utils.ts @@ -1,16 +1,24 @@ export function clearWhitespaces(text: string): string { - if (!text) return text; - let clearedText = text; while (clearedText.startsWith(' ') || clearedText.startsWith('\n')) { - while (clearedText.startsWith(' ')) clearedText = clearedText.substring(1); - while (clearedText.startsWith('\n')) clearedText = clearedText.substring(2); + if (clearedText.startsWith(' ')) { + clearedText = clearedText.replace(' ', ''); + } + + if (clearedText.startsWith('\n')) { + clearedText = clearedText.replace('\n', ''); + } } while (clearedText.endsWith(' ') || clearedText.endsWith('\n')) { - while (clearedText.endsWith(' ')) clearedText = clearedText.substring(0, clearedText.length - 1); - while (clearedText.endsWith('\n')) clearedText = clearedText.substring(0, clearedText.length - 2); + if (clearedText.endsWith(' ')) { + clearedText = clearedText.substring(0, clearedText.length - 1); + } + + if (clearedText.endsWith('\n')) { + clearedText = clearedText.substring(0, clearedText.length - 2); + } } return clearedText;