docgen wip

Author: Amxx

docs/config.js docs/config.mjsdocs/config.js renamed to docs/config.mjs

@@ -1,8 +1,8 @@
-const path = require('path');
-const fs = require('fs');
+import path from 'path';
+import fs from 'fs';
 
 /** @type import('solidity-docgen/dist/config').UserConfig */
-module.exports = {
+export default {
   outputDir: 'docs/modules/api/pages',
   templates: 'docs/templates',
   exclude: ['mocks'],

docs/templates/contract.hbs

@@ -8,7 +8,7 @@
 
 [.contract]
 [[{{anchor}}]]
-=== `++{{name}}++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v{{oz-version}}/{{__item_context.file.absolutePath}}[{github-icon},role=heading-link]
+=== `++{{name}}++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v{{ozVersion}}/{{__item_context.file.absolutePath}}[{github-icon},role=heading-link]
 
 [.hljs-theme-light.nopadding]
 ```solidity
@@ -27,11 +27,11 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";
 --
 {{/if}}
 
-{{#if has-functions}}
+{{#if hasFunctions}}
 [.contract-index]
 .Functions
 --
-{{#each inherited-functions}}
+{{#each inheritedFunctions}}
 {{#unless @first}}
 [.contract-subindex-inherited]
 .{{contract.name}}
@@ -44,7 +44,7 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";
 --
 {{/if}}
 
-{{#if has-events}}
+{{#if hasEvents}}
 [.contract-index]
 .Events
 --
@@ -61,7 +61,7 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";
 --
 {{/if}}
 
-{{#if has-errors}}
+{{#if hasErrors}}
 [.contract-index]
 .Errors
 --
@@ -78,7 +78,7 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";
 --
 {{/if}}
 
-{{#if has-internal-variables}}
+{{#if hasInternalVariables}}
 [.contract-index]
 .Internal Variables
 --
@@ -87,7 +87,7 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";
 [.contract-subindex-inherited]
 .{{name}}
 {{/unless}}
-{{#each internal-variables}}
+{{#each internalVariables}}
 * {xref-{{anchor~}} }[`++{{typeDescriptions.typeString}} {{#if constant}}constant{{/if}} {{name}}++`]
 {{/each}}
 
@@ -98,7 +98,7 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";
 {{#each modifiers}}
 [.contract-item]
 [[{{anchor}}]]
-==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}})++` [.item-kind]#modifier#
+==== `[.contract-item-name]#++{{name}}++#++({{typedParams params}})++` [.item-kind]#modifier#
 
 {{{natspec.dev}}}
 
@@ -107,7 +107,7 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";
 {{#each functions}}
 [.contract-item]
 [[{{anchor}}]]
-==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}}){{#if returns2}} → {{typed-params returns2}}{{/if}}++` [.item-kind]#{{visibility}}#
+==== `[.contract-item-name]#++{{name}}++#++({{typedParams params}}){{#if returns2}} → {{typedParams returns2}}{{/if}}++` [.item-kind]#{{visibility}}#
 
 {{{natspec.dev}}}
 
@@ -116,7 +116,7 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";
 {{#each events}}
 [.contract-item]
 [[{{anchor}}]]
-==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}})++` [.item-kind]#event#
+==== `[.contract-item-name]#++{{name}}++#++({{typedParams params}})++` [.item-kind]#event#
 
 {{{natspec.dev}}}
 
@@ -125,13 +125,13 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";
 {{#each errors}}
 [.contract-item]
 [[{{anchor}}]]
-==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}})++` [.item-kind]#error#
+==== `[.contract-item-name]#++{{name}}++#++({{typedParams params}})++` [.item-kind]#error#
 
 {{{natspec.dev}}}
 
 {{/each}}
 
-{{#each internal-variables}}
+{{#each internalVariables}}
 [.contract-item]
 [[{{anchor}}]]
 ==== `{{typeDescriptions.typeString}} [.contract-item-name]#++{{name}}++#` [.item-kind]#internal{{#if constant}} constant{{/if}}#

docs/templates/helpers.js docs/templates/helpers.tsdocs/templates/helpers.js renamed to docs/templates/helpers.ts

@@ -1,23 +1,23 @@
-const { version } = require('../../package.json');
+import { version } from '../../package.json';
 
-module.exports['oz-version'] = () => version;
+export const ozVersion = () => version;
 
-module.exports['readme-path'] = opts => {
+export const readmePath = opts => {
   return 'contracts/' + opts.data.root.id.replace(/\.adoc$/, '') + '/README.adoc';
 };
 
-module.exports.names = params => params?.map(p => p.name).join(', ');
+export const names = params => params?.map(p => p.name).join(', ');
 
-module.exports['typed-params'] = params => {
+export const typedParams = params => {
   return params?.map(p => `${p.type}${p.indexed ? ' indexed' : ''}${p.name ? ' ' + p.name : ''}`).join(', ');
 };
 
-const slug = (module.exports.slug = str => {
+export const slug = str => {
   if (str === undefined) {
     throw new Error('Missing argument');
   }
   return str.replace(/\W/g, '-');
-});
+};
 
 const linksCache = new WeakMap();
 
@@ -34,7 +34,7 @@ function getAllLinks(items) {
   return res;
 }
 
-module.exports['with-prelude'] = opts => {
+export const withPrelude = opts => {
   const links = getAllLinks(opts.data.site.items);
   const contents = opts.fn();
   const neededLinks = contents

docs/templates/page.hbs

@@ -1,4 +1,4 @@
 :github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
-{{#with-prelude}}
-{{readme (readme-path)}}
-{{/with-prelude}}
+{{#withPrelude}}
+{{readme (readmePath)}}
+{{/withPrelude}}

docs/templates/properties.js docs/templates/properties.tsdocs/templates/properties.js renamed to docs/templates/properties.ts

@@ -1,7 +1,7 @@
-const { isNodeType, findAll } = require('solidity-ast/utils');
-const { slug } = require('./helpers');
+import { isNodeType, findAll } from 'solidity-ast/utils.js';
+import { slug } from './helpers';
 
-module.exports.anchor = function anchor({ item, contract }) {
+export const anchor = function anchor({ item, contract }) {
   let res = '';
   if (contract) {
     res += contract.name + '-';
@@ -17,7 +17,7 @@ module.exports.anchor = function anchor({ item, contract }) {
   return res;
 };
 
-module.exports.fullname = function fullname({ item }) {
+export const fullname = function fullname({ item }) {
   let res = '';
   res += item.name;
   if ('parameters' in item) {
@@ -33,7 +33,7 @@ module.exports.fullname = function fullname({ item }) {
   return res;
 };
 
-module.exports.inheritance = function ({ item, build }) {
+export const inheritance = function ({ item, build }) {
   if (!isNodeType('ContractDefinition', item)) {
     throw new Error('inheritance modifier used on non-contract');
   }
@@ -43,42 +43,42 @@ module.exports.inheritance = function ({ item, build }) {
     .filter((c, i) => c.name !== 'Context' || i === 0);
 };
 
-module.exports['has-functions'] = function ({ item }) {
+export const hasFunctions = function ({ item }) {
   return item.inheritance.some(c => c.functions.length > 0);
 };
 
-module.exports['has-events'] = function ({ item }) {
+export const hasEvents = function ({ item }) {
   return item.inheritance.some(c => c.events.length > 0);
 };
 
-module.exports['has-errors'] = function ({ item }) {
+export const hasErrors = function ({ item }) {
   return item.inheritance.some(c => c.errors.length > 0);
 };
 
-module.exports['internal-variables'] = function ({ item }) {
+export const internalVariables = function ({ item }) {
   return item.variables.filter(({ visibility }) => visibility === 'internal');
 };
 
-module.exports['has-internal-variables'] = function ({ item }) {
-  return module.exports['internal-variables']({ item }).length > 0;
+export const hasInternalVariables = function ({ item }) {
+  return internalVariables({ item }).length > 0;
 };
 
-module.exports.functions = function ({ item }) {
+export const functions = function ({ item }) {
   return [
     ...[...findAll('FunctionDefinition', item)].filter(f => f.visibility !== 'private'),
     ...[...findAll('VariableDeclaration', item)].filter(f => f.visibility === 'public'),
   ];
 };
 
-module.exports.returns2 = function ({ item }) {
+export const returns2 = function ({ item }) {
   if (isNodeType('VariableDeclaration', item)) {
     return [{ type: item.typeName.typeDescriptions.typeString }];
   } else {
     return item.returns;
   }
 };
 
-module.exports['inherited-functions'] = function ({ item }) {
+export const inheritedFunctions = function ({ item }) {
   const { inheritance } = item;
   const baseFunctions = new Set(inheritance.flatMap(c => c.functions.flatMap(f => f.baseFunctions ?? [])));
   return inheritance.map((contract, i) => ({

hardhat.config.ts

@@ -7,6 +7,7 @@ import hardhatIgnoreWarnings from 'hardhat-ignore-warnings';
 import hardhatMocha from '@nomicfoundation/hardhat-mocha';
 import hardhatNetworkHelpers from '@nomicfoundation/hardhat-network-helpers';
 import hardhatPredeploy from 'hardhat-predeploy';
+import hardhatDocgen from './hardhat/hardhat-solidity-docgen/plugin.ts';
 import hardhatExposed from './hardhat/hardhat-exposed/plugin.ts';
 import hardhatTranspiler from './hardhat/hardhat-transpiler/plugin.ts';
 import hardhatOzContractsHelpers from './hardhat/hardhat-oz-contracts-helpers/plugin.ts';
@@ -36,6 +37,7 @@ export default defineConfig({
     hardhatNetworkHelpers,
     hardhatPredeploy,
     // Local plugins
+    hardhatDocgen,
     hardhatExposed,
     hardhatTranspiler,
     hardhatOzContractsHelpers,
@@ -92,4 +94,5 @@ export default defineConfig({
     include: ['contracts/**/*.sol'],
     exclude: ['**/*WithInit.sol'],
   },
+  docgen: await import('./docs/config.mjs').then(m => m.default),
 });

hardhat/hardhat-solidity-docgen/hook-handlers/config.ts

@@ -0,0 +1,19 @@
+import path from 'node:path';
+
+import type { ConfigHooks } from 'hardhat/types/hooks';
+import { defaults } from '../internal/config.ts';
+
+export type * from '../type-extensions.ts';
+
+export default async (): Promise<Partial<ConfigHooks>> => ({
+  resolveUserConfig: (userConfig, resolveConfigurationVariable, next) =>
+    next(userConfig, resolveConfigurationVariable).then(config => {
+      config.docgen ??= userConfig.docgen ?? defaults;
+      config.docgen.root = config.paths.root;
+      config.docgen.sourcesDir = path
+        .relative(config.paths.root, config.paths.sources.solidity[0]) // TODO: support multiple source directories
+        .split(path.sep)
+        .join(path.posix.sep);
+      return config;
+    }),
+});

hardhat/hardhat-solidity-docgen/internal/common/helpers.ts

@@ -0,0 +1,22 @@
+import { VariableDeclaration } from 'solidity-ast';
+
+export function trim(text: string) {
+  if (typeof text === 'string') {
+    return text.trim();
+  }
+}
+
+export function joinLines(text?: string) {
+  if (typeof text === 'string') {
+    return text.replace(/[\r\n]+/g, ' ');
+  }
+}
+
+/**
+ * Format a variable as its type followed by its name, if available.
+ */
+export function formatVariable(v: VariableDeclaration): string {
+  return [v.typeName?.typeDescriptions.typeString!].concat(v.name || []).join(' ');
+}
+
+export const eq = (a: unknown, b: unknown) => a === b;