solidity-docgen - npm Package Compare versions

Comparing version 0.6.0-beta.1 to 0.6.0-beta.2

dist/accessors.d.ts

@@ -1,4 +0,5 @@
-import { ErrorDefinition, EventDefinition, FunctionDefinition, ModifierDefinition, VariableDeclaration } from 'solidity-ast';
+import { EnumDefinition, ErrorDefinition, EventDefinition, FunctionDefinition, ModifierDefinition, StructDefinition, UserDefinedValueTypeDefinition, VariableDeclaration } from 'solidity-ast';
 import { NatSpec } from './utils/natspec';
 import { DocItemWithContext } from './site';
+declare type TypeDefinition = StructDefinition | EnumDefinition | UserDefinedValueTypeDefinition;
 /**
@@ -27,4 +28,5 @@ * Returns a new object with all of the item properties plus the accessors
     variables(item: DocItemWithContext): VariableDeclaration[] | undefined;
+    types(item: DocItemWithContext): TypeDefinition[] | undefined;
 };
 export {};
 //# sourceMappingURL=accessors.d.ts.map

dist/accessors.js

@@ -20,8 +20,8 @@ "use strict";
 function getParams(params, natspec) {
-    return params.parameters.map(p => {
-        var _a, _b;
+    return params.parameters.map((p, i) => {
+        var _a;
         return ({
             name: p.name,
             type: p.typeDescriptions.typeString,
-            natspec: (_b = (_a = natspec.params) === null || _a === void 0 ? void 0 : _a.find(q => p.name === q.name)) === null || _b === void 0 ? void 0 : _b.description,
+            natspec: (_a = natspec === null || natspec === void 0 ? void 0 : natspec.find((q, j) => q.name === undefined ? i === j : p.name === q.name)) === null || _a === void 0 ? void 0 : _a.description,
         });
@@ -48,2 +48,3 @@ });
     signature(item) {
+        var _a;
         switch (item.nodeType) {
@@ -54,4 +55,9 @@ case 'ContractDefinition':
                 const name = exports.accessors.name(item);
-                return `${name}(${item.parameters.parameters.map(a => { var _a; return (_a = a.typeName) === null || _a === void 0 ? void 0 : _a.typeDescriptions.typeString; }).join(',')})`;
+                const params = item.parameters.parameters.map(a => { var _a; return [(_a = a.typeName) === null || _a === void 0 ? void 0 : _a.typeDescriptions.typeString].concat(a.name || []).join(' '); });
+                return `${name}(${params.join(', ')})`;
             }
+            case 'VariableDeclaration': {
+                const name = exports.accessors.name(item);
+                return `${(_a = item.typeName) === null || _a === void 0 ? void 0 : _a.typeDescriptions.typeString} ${name}`;
+            }
         }
@@ -62,3 +68,3 @@ },
             const natspec = exports.accessors.natspec(item);
-            return getParams(item.parameters, natspec);
+            return getParams(item.parameters, natspec.params);
         }
@@ -69,3 +75,3 @@ },
             const natspec = exports.accessors.natspec(item);
-            return getParams(item.returnParameters, natspec);
+            return getParams(item.returnParameters, natspec.returns);
         }
@@ -90,3 +96,6 @@ },
     },
+    types(item) {
+        return [...(0, utils_1.findAll)(['StructDefinition', 'EnumDefinition', 'UserDefinedValueTypeDefinition'], item)];
+    },
 };
 //# sourceMappingURL=accessors.js.map

dist/main.js

@@ -58,13 +58,18 @@ "use strict";
     for (const nameOrPath of templates) {
-        const dir = await (0, fs_exists_1.findExists)(path_1.default.resolve(root, nameOrPath), path_1.default.resolve(__dirname, './templates', nameOrPath));
-        if (dir === undefined) {
+        // Look in src because built-in templates are not copied to dist
+        const templatesDir = await (0, fs_exists_1.findIn)(nameOrPath, [root, path_1.default.join(__dirname, '../src/templates')]);
+        if (templatesDir === undefined) {
             throw new Error(`Templates directory '${nameOrPath}' not found`);
         }
-        for (const t of await fs_1.promises.readdir(dir)) {
+        for (const t of await fs_1.promises.readdir(templatesDir)) {
             const { name, ext } = path_1.default.parse(t);
             if (!(name in partials) && ext === '.hbs') {
-                partials[name] = await fs_1.promises.readFile(path_1.default.join(dir, t), 'utf8');
+                partials[name] = await fs_1.promises.readFile(path_1.default.join(templatesDir, t), 'utf8');
             }
         }
-        const h = await Promise.resolve().then(() => __importStar(require(path_1.default.join(dir, 'helpers')))).catch(() => undefined);
+        const helpersDir = await (0, fs_exists_1.findIn)(nameOrPath, [root, path_1.default.join(__dirname, './templates')]);
+        if (helpersDir === undefined) {
+            throw new Error(`Templates directory '${nameOrPath}' not found`);
+        }
+        const h = await Promise.resolve().then(() => __importStar(require(path_1.default.join(helpersDir, 'helpers')))).catch(() => undefined);
         for (const name in h) {
@@ -71,0 +76,0 @@ if (!(name in helpers) && typeof h[name] === 'function') {

dist/render.js

@@ -25,3 +25,3 @@ "use strict";
 exports.render = render;
-const itemPartialName = (item) => accessors_1.accessors.type(item).replace(' ', '').toLowerCase();
+const itemPartialName = (item) => accessors_1.accessors.type(item).replace(/ /g, '-').toLowerCase();
 exports.itemPartialName = itemPartialName;
@@ -28,0 +28,0 @@ function itemPartial(item, options) {

dist/templates/markdown/helpers.d.ts

@@ -1,2 +0,7 @@
-import { DocItemWithContext } from "../../site";
+import { HelperOptions } from 'handlebars';
+import { DocItemWithContext } from '../../site';
+declare type HLevel = {
+    hlevel?: number;
+};
+declare type DocItemWithHLevel = DocItemWithContext & HLevel;
 /**
@@ -10,7 +15,8 @@ * Returns a Markdown heading marker. An optional `hlevel` context variable increases the heading level.
  */
-export declare function h(this: DocItemWithContext & {
-    hlevel?: number;
-}, hsublevel: number | object): string;
+export declare function h(this: DocItemWithHLevel, hsublevel: number | HelperOptions): string;
+export declare function hsection(this: DocItemWithHLevel, hsublevel: number, opts: HelperOptions): string;
+export declare function hsection(this: DocItemWithHLevel, opts: HelperOptions): string;
 export declare function trim(text: string): string | undefined;
 export declare function joinLines(text?: string): string | undefined;
+export {};
 //# sourceMappingURL=helpers.d.ts.map

dist/templates/markdown/helpers.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.joinLines = exports.trim = exports.h = void 0;
+exports.joinLines = exports.trim = exports.hsection = exports.h = void 0;
+const handlebars_1 = require("handlebars");
 /**
@@ -13,8 +14,29 @@ * Returns a Markdown heading marker. An optional `hlevel` context variable increases the heading level.
 function h(hsublevel) {
-    var _a;
+    ({ hsublevel } = getHSublevel(hsublevel));
     hsublevel = typeof hsublevel === 'number' ? Math.max(1, hsublevel) : 1;
-    return new Array(((_a = this.hlevel) !== null && _a !== void 0 ? _a : 1) + hsublevel - 1).fill('#').join('');
+    return new Array(getHLevel(this) + hsublevel - 1).fill('#').join('');
 }
 exports.h = h;
 ;
+function hsection(hsublevel, opts) {
+    ({ hsublevel, opts } = getHSublevel(hsublevel, opts));
+    const hlevel = getHLevel(this) + hsublevel;
+    const ctx = handlebars_1.Utils.extend({}, this, { hlevel });
+    return opts.fn(ctx, opts);
+}
+exports.hsection = hsection;
+function getHSublevel(hsublevel, opts) {
+    if (typeof hsublevel === 'number') {
+        opts = opts;
+        return { hsublevel: Math.max(1, hsublevel), opts };
+    }
+    else {
+        opts = hsublevel;
+        return { hsublevel: 1, opts };
+    }
+}
+function getHLevel(ctx) {
+    var _a;
+    return (_a = ctx.hlevel) !== null && _a !== void 0 ? _a : 1;
+}
 function trim(text) {
@@ -21,0 +43,0 @@ if (typeof text === 'string') {

dist/utils/fs-exists.d.ts

 export declare function exists(path: string, mode?: number): Promise<boolean>;
 export declare function findExists(...paths: string[]): Promise<string | undefined>;
+export declare function findIn(f: string, dirs: string[]): Promise<string | undefined>;
 //# sourceMappingURL=fs-exists.d.ts.map

dist/utils/fs-exists.js

 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.findExists = exports.exists = void 0;
+exports.findIn = exports.findExists = exports.exists = void 0;
 const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
 async function exists(path, mode = fs_1.constants.R_OK) {
@@ -23,2 +27,6 @@ try {
 exports.findExists = findExists;
+async function findIn(f, dirs) {
+    return findExists(...dirs.map(d => path_1.default.resolve(d, f)));
+}
+exports.findIn = findIn;
 //# sourceMappingURL=fs-exists.js.map

dist/utils/natspec.js

@@ -65,4 +65,4 @@ "use strict";
         if (tag === 'inheritdoc') {
-            if (item.nodeType !== 'FunctionDefinition') {
-                throw new Error(`Expected function but saw ${accessors_1.accessors.type(item)}`);
+            if (!(item.nodeType === 'FunctionDefinition' || item.nodeType === 'VariableDeclaration')) {
+                throw new Error(`Expected function or variable but saw ${accessors_1.accessors.type(item)}`);
             }
@@ -77,2 +77,6 @@ const parentContractName = content.trim();
     }
+    if (res.dev)
+        res.dev = res.dev.trim();
+    if (res.notice)
+        res.notice = res.notice.trim();
     if (inheritFrom) {
@@ -79,0 +83,0 @@ res = { ...parseNatspec(inheritFrom), ...res };

package.json

 {
   "name": "solidity-docgen",
-  "version": "0.6.0-beta.1",
+  "version": "0.6.0-beta.2",
   "description": "Documentation generator for Solidity smart contracts.",
@@ -18,3 +18,3 @@ "repository": "github:OpenZeppelin/solidity-docgen",
   "scripts": {
-    "build": "tsc && copyfiles -u 1 src/**/*.hbs dist/",
+    "build": "tsc",
     "clean": "hardhat clean && rimraf dist tsconfig.tsbuildinfo",
@@ -37,3 +37,2 @@ "coverage": "c8 npm run test",
     "code-style": "github:OpenZeppelin/code-style",
-    "copyfiles": "^2.4.1",
     "hardhat": "^2.8.0",
@@ -40,0 +39,0 @@ "openzeppelin-docs-utils": "github:OpenZeppelin/docs-utils",

src/accessors.ts

@@ -1,2 +0,2 @@
-import { ErrorDefinition, EventDefinition, FunctionDefinition, ModifierDefinition, ParameterList, VariableDeclaration } from 'solidity-ast';
+import { EnumDefinition, ErrorDefinition, EventDefinition, FunctionDefinition, ModifierDefinition, ParameterList, StructDefinition, UserDefinedValueTypeDefinition, VariableDeclaration } from 'solidity-ast';
 import { findAll, isNodeType } from 'solidity-ast/utils';
@@ -7,2 +7,4 @@ import { NatSpec, parseNatspec } from './utils/natspec';
 
+type TypeDefinition = StructDefinition | EnumDefinition | UserDefinedValueTypeDefinition;
+
 /**
@@ -26,7 +28,7 @@ * Returns a new object with all of the item properties plus the accessors
 
-function getParams(params: ParameterList, natspec: NatSpec): Param[] {
-  return params.parameters.map(p => ({
+function getParams(params: ParameterList, natspec: NatSpec['params'] | NatSpec['returns']): Param[] {
+  return params.parameters.map((p, i) => ({
     name: p.name,
     type: p.typeDescriptions.typeString!,
-    natspec: natspec.params?.find(q => p.name === q.name)?.description,
+    natspec: natspec?.find((q, j) => q.name === undefined ? i === j : p.name === q.name)?.description,
   }));
@@ -61,4 +63,12 @@ }
         const name = accessors.name(item);
-        return `${name}(${item.parameters.parameters.map(a => a.typeName?.typeDescriptions.typeString!).join(',')})`;
+        const params = item.parameters.parameters.map(a =>
+          [a.typeName?.typeDescriptions.typeString!].concat(a.name || []).join(' ')
+        );
+        return `${name}(${params.join(', ')})`;
       }
+
+      case 'VariableDeclaration': {
+        const name = accessors.name(item);
+        return `${item.typeName?.typeDescriptions.typeString!} ${name}`;
+      }
     }
@@ -70,3 +80,3 @@ },
       const natspec = accessors.natspec(item);
-      return getParams(item.parameters, natspec);
+      return getParams(item.parameters, natspec.params);
     }
@@ -78,3 +88,3 @@ },
       const natspec = accessors.natspec(item);
-      return getParams(item.returnParameters, natspec);
+      return getParams(item.returnParameters, natspec.returns);
     }
@@ -104,2 +114,6 @@ },
   },
+
+  types(item: DocItemWithContext): TypeDefinition[] | undefined {
+    return [...findAll(['StructDefinition', 'EnumDefinition', 'UserDefinedValueTypeDefinition'], item)];
+  },
 };

src/main.ts

@@ -6,3 +6,3 @@ import path from 'path';
 import { Build, PageAssigner, buildSite } from './site';
-import { exists, findExists } from './utils/fs-exists';
+import { exists, findIn } from './utils/fs-exists';
 import { ensureArray } from './utils/ensure-array';
@@ -40,19 +40,21 @@ import { Config, defaults } from './config';
   for (const nameOrPath of templates) {
-    const dir = await findExists(
-      path.resolve(root, nameOrPath),
-      path.resolve(__dirname, './templates', nameOrPath),
-    );
-
-    if (dir === undefined) {
+    // Look in src because built-in templates are not copied to dist
+    const templatesDir = await findIn(nameOrPath, [root, path.join(__dirname, '../src/templates')]);
+    if (templatesDir === undefined) {
       throw new Error(`Templates directory '${nameOrPath}' not found`);
     }
 
-    for (const t of await fs.readdir(dir)) {
+    for (const t of await fs.readdir(templatesDir)) {
       const { name, ext } = path.parse(t);
       if (!(name in partials) && ext === '.hbs') {
-        partials[name] = await fs.readFile(path.join(dir, t), 'utf8');
+        partials[name] = await fs.readFile(path.join(templatesDir, t), 'utf8');
       }
     }
 
-    const h = await import(path.join(dir, 'helpers')).catch(() => undefined);
+    const helpersDir = await findIn(nameOrPath, [root, path.join(__dirname, './templates')]);
+    if (helpersDir === undefined) {
+      throw new Error(`Templates directory '${nameOrPath}' not found`);
+    }
+
+    const h = await import(path.join(helpersDir, 'helpers')).catch(() => undefined);
     for (const name in h) {
@@ -59,0 +61,0 @@ if (!(name in helpers) && typeof h[name] === 'function') {

src/render.ts

@@ -39,3 +39,3 @@ import Handlebars, { RuntimeOptions } from 'handlebars';
 
-export const itemPartialName = (item: DocItemWithContext) => accessors.type(item).replace(' ', '').toLowerCase();
+export const itemPartialName = (item: DocItemWithContext) => accessors.type(item).replace(/ /g, '-').toLowerCase();
 
@@ -42,0 +42,0 @@ function itemPartial(item: DocItemWithContext, options?: RuntimeOptions) {

src/templates/markdown/helpers.ts

@@ -1,4 +0,8 @@
-import { TypeName } from "solidity-ast";
-import { DocItemWithContext } from "../../site";
+import { HelperOptions, Utils } from 'handlebars';
+import { TypeName } from 'solidity-ast';
+import { DocItemWithContext } from '../../site';
 
+type HLevel = { hlevel?: number };
+type DocItemWithHLevel = DocItemWithContext & HLevel;
+
 /**
@@ -12,7 +16,36 @@ * Returns a Markdown heading marker. An optional `hlevel` context variable increases the heading level.
  */
-export function h(this: DocItemWithContext & { hlevel?: number }, hsublevel: number | object) {
+export function h(this: DocItemWithHLevel, hsublevel: number | HelperOptions) {
+  ({ hsublevel } = getHSublevel(hsublevel));
   hsublevel = typeof hsublevel === 'number' ? Math.max(1, hsublevel) : 1;
-  return new Array((this.hlevel ?? 1) + hsublevel - 1).fill('#').join('');
+  return new Array(getHLevel(this) + hsublevel - 1).fill('#').join('');
 };
 
+export function hsection(this: DocItemWithHLevel, hsublevel: number, opts: HelperOptions): string;
+export function hsection(this: DocItemWithHLevel, opts: HelperOptions): string;
+export function hsection(this: DocItemWithHLevel, hsublevel: number | HelperOptions, opts?: HelperOptions) {
+  ({ hsublevel, opts } = getHSublevel(hsublevel, opts));
+  const hlevel = getHLevel(this) + hsublevel;
+  const ctx = Utils.extend({}, this, { hlevel });
+  return opts.fn(ctx, opts);
+}
+
+/**
+ * Helper for dealing with the optional hsublevel argument.
+ */
+function getHSublevel(hsublevel: number | HelperOptions): { hsublevel: number };
+function getHSublevel(hsublevel: number | HelperOptions, opts?: HelperOptions): { hsublevel: number, opts: HelperOptions };
+function getHSublevel(hsublevel: number | HelperOptions, opts?: HelperOptions) {
+  if (typeof hsublevel === 'number') {
+    opts = opts!;
+    return { hsublevel: Math.max(1, hsublevel), opts };
+  } else {
+    opts = hsublevel;
+    return { hsublevel: 1, opts };
+  }
+}
+
+function getHLevel(ctx: HLevel): number {
+  return ctx.hlevel ?? 1;
+}
+
 export function trim(text: string) {
@@ -19,0 +52,0 @@ if (typeof text === 'string') {

src/utils/fs-exists.ts

 import { promises as fs, constants } from 'fs';
+import path from 'path';
 
@@ -19,1 +20,5 @@ export async function exists(path: string, mode: number = constants.R_OK): Promise<boolean> {
 }
+
+export async function findIn(f: string, dirs: string[]): Promise<string | undefined> {
+  return findExists(...dirs.map(d => path.resolve(d, f)));
+}

src/utils/natspec.ts

@@ -89,4 +89,4 @@ import { FunctionDefinition } from 'solidity-ast';
     if (tag === 'inheritdoc') {
-      if (item.nodeType !== 'FunctionDefinition') {
-        throw new Error(`Expected function but saw ${accessors.type(item)}`);
+      if (!(item.nodeType === 'FunctionDefinition' || item.nodeType === 'VariableDeclaration')) {
+        throw new Error(`Expected function or variable but saw ${accessors.type(item)}`);
       }
@@ -102,2 +102,5 @@ const parentContractName = content.trim();
 
+  if (res.dev) res.dev = res.dev.trim();
+  if (res.notice) res.notice = res.notice.trim();
+
   if (inheritFrom) {
@@ -104,0 +107,0 @@ res = { ...parseNatspec(inheritFrom as DocItemWithContext), ...res };

New alerts

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

Fixed alerts

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

100479

increased by8.06%

Dev dependency count

9

decreased by-10%

Lines of code

1651

increased by6.79%

Worsened metrics

Number of package files

119

decreased by-4.03%

No dependency changes