Merge pull request #1 from ecp-eth/feat/struct-links

michalkvasnicak · web-flow · commit 46da87858059 · 2025-06-16T07:50:34.000+02:00
feat: struct/enum links and support for natspec
diff --git a/.gitignore b/.gitignore
@@ -4,3 +4,4 @@ node_modules
 /dist
 /fixtures/*/output
 /coverage
+*temp.json
diff --git a/ava.config.js b/ava.config.js
@@ -2,6 +2,8 @@ export default {
   ignoredByWatcher: [
     '**/*.{ts,map,tsbuildinfo}',
     'fixtures/*/output',
+    'sitemap-fixtures/*/output',
+    'source-fixtures/*/output',
   ],
   typescript: {
     rewritePaths: { 'src/': 'dist/' },
diff --git a/fixtures/custom/templates/arg.hbs b/fixtures/custom/templates/arg.hbs
@@ -0,0 +1 @@
+{{#if name}}{{type}} {{name}}{{else}}{{type}}{{/if}}
diff --git a/fixtures/dependencies/templates/arg.hbs b/fixtures/dependencies/templates/arg.hbs
@@ -0,0 +1 @@
+{{#if name}}{{type}} {{name}}{{else}}{{type}}{{/if}}
diff --git a/fixtures/helpers/templates/arg.hbs b/fixtures/helpers/templates/arg.hbs
@@ -0,0 +1 @@
+{{#if name}}{{type}} {{name}}{{else}}{{type}}{{/if}}
diff --git a/fixtures/inheritdoc/templates/arg.hbs b/fixtures/inheritdoc/templates/arg.hbs
@@ -0,0 +1 @@
+{{#if name}}{{type}} {{name}}{{else}}{{type}}{{/if}}
diff --git a/fixtures/solc-0.8/input/Bar.sol b/fixtures/solc-0.8/input/Bar.sol
@@ -0,0 +1,10 @@
+pragma solidity ^0.8;
+
+struct TestStruct {
+    uint256 x;
+}
+
+enum TestEnum {
+    A,
+    B
+}
diff --git a/fixtures/solc-0.8/input/Foo.sol b/fixtures/solc-0.8/input/Foo.sol
@@ -1,7 +1,8 @@
 pragma solidity ^0.8;
 
-contract Bar {
-}
+import {TestStruct as BarTestStruct, TestEnum as BarTestEnum} from "./Bar.sol";
+
+contract Bar {}
 
 /**
  * @dev some devdoc
@@ -10,28 +11,5 @@ contract Foo is Bar {
     /**
      * @dev and a function
      */
-    function foo() external {
-    }
-}
-
-/**
- * Some Unicode characters: ⇌ £ ह 𐍈 ⇌ £ ह 𐍈
- */
-contract X {
-    /**
-     * A function
-     */
-    function foo() external {}
-
-    /**
-     * @notice this is a struct
-     * @param a is a uint256
-     * @param b is a address
-     * @param c is a string
-     */
-    struct TheStruct {
-        uint256 a;
-        address b;
-        string c;
-    }
+    function foo(BarTestStruct calldata a, BarTestEnum b) external {}
 }
diff --git a/fixtures/struct-enum/input/EnumAndStruct.sol b/fixtures/struct-enum/input/EnumAndStruct.sol
@@ -1,17 +1,28 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity ^0.6;
+pragma solidity ^0.8;
 
 contract StructAndEnum {
-  /// @dev This is foo
-  enum Foo {
-    FOO,
-    BAR
-  }
+    /// @dev This is foo dev
+    /// @notice This is foo notice
+    enum Foo {
+        /// @dev This is foo dev
+        /// @notice This is foo notice
+        FOO,
+        /// @dev This is bar dev
+        /// @notice This is bar notice
+        BAR
+    }
 
-  /// @dev This is bar
-  struct Bar {
-    uint256 foo;
-    string bar;
-  }
+    /// Test
+    /// @notice This is baz notice
+    /// @dev This is bar dev
+    struct Bar {
+        /// @dev This is foo
+        /// @notice This is foo notice
+        uint256 foo;
+        /// @dev This is bar dev
+        /// @notice This is bar notice
+        string bar;
+    }
 }
diff --git a/fixtures/struct-enum/solc b/fixtures/struct-enum/solc
@@ -0,0 +1 @@
+solc-0-8
diff --git a/fixtures/struct-enum/templates/arg.hbs b/fixtures/struct-enum/templates/arg.hbs
@@ -0,0 +1 @@
+{{#if name}}{{type}} {{name}}{{else}}{{type}}{{/if}}
diff --git a/fixtures/struct-enum/templates/contract.hbs b/fixtures/struct-enum/templates/contract.hbs
@@ -1,19 +1,35 @@
 {{#each ownStructs}}
 ### `{{name}}`
 
+{{{natspec.userdoc}}}
+
+{{{natspec.devdoc}}}
+
 {{#each members}}
-- {{type}} {{name}}
+#### {{type}} {{name}}
+
+{{{natspec.devdoc}}}
+
+{{{natspec.userdoc}}}
+
 {{/each}}
 
 {{/each}}
 
 {{#each ownEnums}}
 ### `{{name}}`
 
-All members: {{members}}
+{{{natspec.userdoc}}}
+
+{{{natspec.devdoc}}}
 
 {{#each members}}
-  - {{.}}
+#### `{{name}}`
+
+{{{natspec.devdoc}}}
+
+{{{natspec.userdoc}}}
+
 {{/each}}
 
 {{/each}}
diff --git a/package.json b/package.json
@@ -35,7 +35,8 @@
     "minimatch": "^5.0.0",
     "never": "^1.1.0",
     "semver": "^7.3.2",
-    "solc": "^0.6.7"
+    "solc": "^0.6.7",
+    "solidity-ast": "^0.4.60"
   },
   "devDependencies": {
     "@ava/typescript": "^2.0.0",
@@ -66,5 +67,6 @@
     "automatic",
     "generator"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }
diff --git a/sitemap-fixtures/filter-nested-subdirectories/input/sub/Bar.sol b/sitemap-fixtures/filter-nested-subdirectories/input/sub/Bar.sol
@@ -0,0 +1,3 @@
+pragma solidity ^0.8;
+
+contract Bar {}
diff --git a/sitemap-fixtures/filter-nested-subdirectories/input/sub/sub2/Foo.sol b/sitemap-fixtures/filter-nested-subdirectories/input/sub/sub2/Foo.sol
@@ -0,0 +1,3 @@
+pragma solidity ^0.8;
+
+contract Foo {}
diff --git a/sitemap-fixtures/filter-subdirectory/input/Foo.sol b/sitemap-fixtures/filter-subdirectory/input/Foo.sol
@@ -0,0 +1,3 @@
+pragma solidity ^0.8;
+
+contract Foo {}
diff --git a/sitemap-fixtures/filter-subdirectory/input/sub/Bar.sol b/sitemap-fixtures/filter-subdirectory/input/sub/Bar.sol
@@ -0,0 +1,3 @@
+pragma solidity ^0.8;
+
+contract Bar {}
diff --git a/sitemap-fixtures/links/input/sub1/Bar.sol b/sitemap-fixtures/links/input/sub1/Bar.sol
@@ -0,0 +1,3 @@
+pragma solidity ^0.8;
+
+contract Bar {}
diff --git a/sitemap-fixtures/links/input/sub2/Foo.sol b/sitemap-fixtures/links/input/sub2/Foo.sol
@@ -0,0 +1,3 @@
+pragma solidity ^0.8;
+
+contract Foo {}
diff --git a/sitemap-fixtures/single-readme-multiple-contracts/input/Foo.sol b/sitemap-fixtures/single-readme-multiple-contracts/input/Foo.sol
@@ -0,0 +1,5 @@
+pragma solidity ^0.8;
+
+contract Foo {}
+
+contract Bar {}
diff --git a/sitemap-fixtures/single-readme/input/main.sol b/sitemap-fixtures/single-readme/input/main.sol
@@ -0,0 +1 @@
+pragma solidity ^0.8;
diff --git a/source-fixtures/contracts-in-scope-from-imported-files-transitively/input/Bar.sol b/source-fixtures/contracts-in-scope-from-imported-files-transitively/input/Bar.sol
@@ -0,0 +1,5 @@
+pragma solidity ^0.8;
+
+import "./Foo.sol";
+
+contract Bar {}
diff --git a/source-fixtures/contracts-in-scope-from-imported-files-transitively/input/Baz.sol b/source-fixtures/contracts-in-scope-from-imported-files-transitively/input/Baz.sol
@@ -0,0 +1,5 @@
+pragma solidity ^0.8;
+
+import "./Bar.sol";
+
+contract Baz {}
diff --git a/source-fixtures/contracts-in-scope-from-imported-files-transitively/input/Foo.sol b/source-fixtures/contracts-in-scope-from-imported-files-transitively/input/Foo.sol
@@ -0,0 +1,3 @@
+pragma solidity ^0.8;
+
+contract Foo {}
diff --git a/source-fixtures/contracts-in-scope-from-imported-files-with-alias/input/Bar.sol b/source-fixtures/contracts-in-scope-from-imported-files-with-alias/input/Bar.sol
@@ -0,0 +1,5 @@
+pragma solidity ^0.8;
+
+import {Foo as FooRenamed} from "./Foo.sol";
+
+contract Bar {}
diff --git a/source-fixtures/contracts-in-scope-from-imported-files-with-alias/input/Foo.sol b/source-fixtures/contracts-in-scope-from-imported-files-with-alias/input/Foo.sol
@@ -0,0 +1,3 @@
+pragma solidity ^0.8;
+
+contract Foo {}
diff --git a/source-fixtures/contracts-in-scope-from-imported-files/input/Bar.sol b/source-fixtures/contracts-in-scope-from-imported-files/input/Bar.sol
@@ -0,0 +1,5 @@
+pragma solidity ^0.8;
+
+import "./Foo.sol";
+
+contract Bar {}
diff --git a/source-fixtures/contracts-in-scope-from-imported-files/input/Foo.sol b/source-fixtures/contracts-in-scope-from-imported-files/input/Foo.sol
@@ -0,0 +1,3 @@
+pragma solidity ^0.8;
+
+contract Foo {}
diff --git a/source-fixtures/grouped-inherited-items/input/Foo.sol b/source-fixtures/grouped-inherited-items/input/Foo.sol
@@ -0,0 +1,11 @@
+pragma solidity ^0.8;
+
+contract Foo {
+    function fooTest() public {}
+}
+
+contract Bar {
+    function barTest() public {}
+}
+
+contract Child is Bar, Foo {}
diff --git a/source-fixtures/inherited-state-variable/input/Foo.sol b/source-fixtures/inherited-state-variable/input/Foo.sol
@@ -0,0 +1,9 @@
+pragma solidity ^0.8;
+
+contract Foo {
+    uint256 x;
+}
+
+contract Bar is Foo {
+    uint256 y;
+}
diff --git a/source-fixtures/one-contract/input/Foo.sol b/source-fixtures/one-contract/input/Foo.sol
@@ -0,0 +1,3 @@
+pragma solidity ^0.8;
+
+contract Foo {}
diff --git a/source-fixtures/one-empty-file/input/Foo.sol b/source-fixtures/one-empty-file/input/Foo.sol
diff --git a/source-fixtures/one-inherited-function/input/Foo.sol b/source-fixtures/one-inherited-function/input/Foo.sol
@@ -0,0 +1,7 @@
+pragma solidity ^0.8;
+
+contract Foo {
+    function test() public {}
+}
+
+contract Bar is Foo {}
diff --git a/source-fixtures/one-multiply-inherited-function/input/Foo.sol b/source-fixtures/one-multiply-inherited-function/input/Foo.sol
@@ -0,0 +1,13 @@
+pragma solidity ^0.8;
+
+contract Foo {
+    function test() public virtual {}
+}
+
+contract FooFlavor {
+    function test() public virtual {}
+}
+
+contract Bar is Foo, FooFlavor {
+    function test() public override(Foo, FooFlavor) {}
+}
diff --git a/source-fixtures/one-own-function-with-struct-as-argument/input/Foo.sol b/source-fixtures/one-own-function-with-struct-as-argument/input/Foo.sol
@@ -0,0 +1,9 @@
+pragma solidity ^0.8;
+
+contract Foo {
+    struct Bar {
+        uint256 x;
+    }
+
+    function test(Bar memory bar) public {}
+}
diff --git a/source-fixtures/read-output-0-6/input/Foo.sol b/source-fixtures/read-output-0-6/input/Foo.sol
@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.6;
+
+contract Foo {
+    uint public x;
+    /**
+     * @dev docs
+     */
+    function fun(uint a) public pure returns (uint r) {
+        return a;
+    }
+    event Ev(uint a);
+    modifier mod(uint a) {
+        _;
+    }
+    receive() external payable {}
+}
diff --git a/source-fixtures/state-variable/input/Foo.sol b/source-fixtures/state-variable/input/Foo.sol
@@ -0,0 +1,5 @@
+pragma solidity ^0.8;
+
+contract Foo {
+    uint256 x;
+}
diff --git a/source-fixtures/two-inherited-constructors/input/Foo.sol b/source-fixtures/two-inherited-constructors/input/Foo.sol
@@ -0,0 +1,9 @@
+pragma solidity ^0.8;
+
+contract Foo {
+    constructor(uint256 x) {}
+}
+
+contract FooFlavor is Foo {
+    constructor(string memory x) Foo(1) {}
+}
diff --git a/source-fixtures/two-inherited-functions-with-name-overloading/input/Foo.sol b/source-fixtures/two-inherited-functions-with-name-overloading/input/Foo.sol
@@ -0,0 +1,9 @@
+pragma solidity ^0.8;
+
+contract Foo {
+    function test(uint256 x) public {}
+
+    function test(string memory x) public {}
+}
+
+contract FooFlavor is Foo {}
diff --git a/src/cli.test.ts b/src/cli.test.ts
@@ -3,8 +3,6 @@ import fs from 'promisified/fs';
 import proc from 'child_process';
 import events from 'events';
 
-import { Docgen } from './cli';
-
 for (const f of fs.readdirSync('fixtures')) {
   testFixture(f);
 }
diff --git a/src/cli.test.ts.md b/src/cli.test.ts.md
diff --git a/src/cli.test.ts.snap b/src/cli.test.ts.snap
diff --git a/src/cli.ts b/src/cli.ts
diff --git a/src/docgen.ts b/src/docgen.ts
diff --git a/src/sitemap.test.ts b/src/sitemap.test.ts
diff --git a/src/solc-output-builder.ts b/src/solc-output-builder.ts
diff --git a/src/solc.ts b/src/solc.ts
diff --git a/src/source.test.ts b/src/source.test.ts
diff --git a/src/source.ts b/src/source.ts
diff --git a/templates/arg.hbs b/templates/arg.hbs
diff --git a/templates/contract.hbs b/templates/contract.hbs
diff --git a/yarn.lock b/yarn.lock

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+{{#if name}}{{type}} {{name}}{{else}}{{type}}{{/if}}`