solidity-docgen - npm Package Compare versions

Comparing version 0.5.13 to 0.5.14

CHANGELOG.md

 # Changelog
 
+## 0.5.14
+
+- Add support for documenting structs and enums: `{{structs}}`, `{{ownStructs}}`, and likewise for enums.
+
 ## 0.5.13
@@ -4,0 +8,0 @@

dist/solc.d.ts

@@ -39,3 +39,3 @@ import { Filter } from './filter';
     }
-    type ContractItem = VariableDeclaration | FunctionDefinition | EventDefinition | ModifierDefinition;
+    type ContractItem = VariableDeclaration | FunctionDefinition | EventDefinition | ModifierDefinition | StructDefinition | EnumDefinition;
     interface VariableDeclaration {
@@ -69,2 +69,18 @@ nodeType: 'VariableDeclaration';
     }
+    interface StructDefinition {
+        nodeType: 'StructDefinition';
+        name: string;
+        members: VariableDeclaration[];
+        visibility: 'internal' | 'external' | 'public' | 'private';
+    }
+    interface EnumDefinition {
+        nodeType: 'EnumDefinition';
+        name: string;
+        members: EnumValue[];
+    }
+    interface EnumValue {
+        nodeType: 'EnumValue';
+        id: number;
+        name: string;
+    }
     interface ParameterList {
@@ -71,0 +87,0 @@ parameters: {

dist/source.d.ts

@@ -49,2 +49,6 @@ declare type ContractTemplate = (contract: SourceContract) => string;
     get ownModifiers(): SourceModifier[];
+    get structs(): SourceStruct[];
+    get ownStructs(): SourceStruct[];
+    get enums(): SourceEnum[];
+    get ownEnums(): SourceEnum[];
     get natspec(): NatSpec;
@@ -55,7 +59,13 @@ get astId(): number;
     readonly contract: SourceContract;
+    protected abstract astNode: Exclude<ast.ContractItem, ast.VariableDeclaration>;
     constructor(contract: SourceContract);
-    protected abstract astNode: Exclude<ast.ContractItem, ast.VariableDeclaration>;
     get name(): string;
     get fullName(): string;
     get anchor(): string;
+}
+declare abstract class SourceFunctionLike extends SourceContractItem {
+    readonly contract: SourceContract;
+    protected abstract astNode: ast.FunctionDefinition | ast.ModifierDefinition | ast.EventDefinition;
+    constructor(contract: SourceContract);
+    get anchor(): string;
     get args(): SourceTypedVariable[];
@@ -76,3 +86,10 @@ get signature(): string;
 }
-declare class SourceFunction extends SourceContractItem {
+declare class SourceStructVariable {
+    readonly struct: SourceStruct;
+    protected readonly astNode: ast.VariableDeclaration;
+    constructor(struct: SourceStruct, astNode: ast.VariableDeclaration);
+    get name(): string;
+    get type(): string;
+}
+declare class SourceFunction extends SourceFunctionLike {
     protected readonly astNode: ast.FunctionDefinition;
@@ -85,10 +102,22 @@ constructor(contract: SourceContract, astNode: ast.FunctionDefinition);
 }
-declare class SourceEvent extends SourceContractItem {
+declare class SourceEvent extends SourceFunctionLike {
     protected readonly astNode: ast.EventDefinition;
     constructor(contract: SourceContract, astNode: ast.EventDefinition);
 }
-declare class SourceModifier extends SourceContractItem {
+declare class SourceModifier extends SourceFunctionLike {
     protected readonly astNode: ast.ModifierDefinition;
     constructor(contract: SourceContract, astNode: ast.ModifierDefinition);
 }
+declare class SourceStruct extends SourceContractItem {
+    protected readonly astNode: ast.StructDefinition;
+    constructor(contract: SourceContract, astNode: ast.StructDefinition);
+    get members(): SourceStructVariable[];
+    get natspec(): {};
+}
+declare class SourceEnum extends SourceContractItem {
+    protected readonly astNode: ast.EnumDefinition;
+    constructor(contract: SourceContract, astNode: ast.EnumDefinition);
+    get members(): string[];
+    get natspec(): {};
+}
 declare class SourceTypedVariable {
@@ -108,2 +137,4 @@ private readonly typeNode;
     modifiers: SourceModifier[];
+    structs: SourceStruct[];
+    enums: SourceEnum[];
 }
@@ -110,0 +141,0 @@ interface NatSpec {

dist/source.js

@@ -112,3 +112,11 @@ "use strict";
     get linkable() {
-        return [this, ...this.ownModifiers, ...this.ownVariables, ...this.ownFunctions, ...this.ownEvents];
+        return [
+            this,
+            ...this.ownModifiers,
+            ...this.ownVariables,
+            ...this.ownFunctions,
+            ...this.ownEvents,
+            ...this.ownStructs,
+            ...this.ownEnums,
+        ];
     }
@@ -148,2 +156,4 @@ get inheritance() {
         const modifiers = lodash_1.groupBy(this.modifiers, f => f.contract.astId);
+        const structs = lodash_1.groupBy(this.structs, f => f.contract.astId);
+        const enums = lodash_1.groupBy(this.enums, f => f.contract.astId);
         return this.inheritance.map(contract => ({
@@ -155,2 +165,4 @@ contract,
             modifiers: modifiers[contract.astId],
+            structs: structs[contract.astId],
+            enums: enums[contract.astId],
         }));
@@ -174,2 +186,18 @@ }
     }
+    get structs() {
+        return lodash_1.flatten(this.inheritance.map(c => c.ownStructs));
+    }
+    get ownStructs() {
+        return this.astNode.nodes
+            .filter(isStructDefinition)
+            .map(n => new SourceStruct(this, n));
+    }
+    get enums() {
+        return lodash_1.flatten(this.inheritance.map(c => c.ownEnums));
+    }
+    get ownEnums() {
+        return this.astNode.nodes
+            .filter(isEnumDefinition)
+            .map(n => new SourceEnum(this, n));
+    }
     get natspec() {
@@ -202,2 +230,8 @@ if (this.astNode.documentation === null || this.astNode.documentation === undefined) {
     memoize_1.memoize
+], SourceContract.prototype, "ownStructs", null);
+__decorate([
+    memoize_1.memoize
+], SourceContract.prototype, "ownEnums", null);
+__decorate([
+    memoize_1.memoize
 ], SourceContract.prototype, "natspec", null);
@@ -216,2 +250,11 @@ exports.SourceContract = SourceContract;
     get anchor() {
+        return `${this.contract.name}-${this.name}`;
+    }
+}
+class SourceFunctionLike extends SourceContractItem {
+    constructor(contract) {
+        super(contract);
+        this.contract = contract;
+    }
+    get anchor() {
         return `${this.contract.name}-${handlebars_1.slug(this.signature)}`;
@@ -234,6 +277,6 @@ }
     memoize_1.memoize
-], SourceContractItem.prototype, "args", null);
+], SourceFunctionLike.prototype, "args", null);
 __decorate([
     memoize_1.memoize
-], SourceContractItem.prototype, "natspec", null);
+], SourceFunctionLike.prototype, "natspec", null);
 class SourceStateVariable {
@@ -264,3 +307,15 @@ constructor(contract, astNode) {
 }
-class SourceFunction extends SourceContractItem {
+class SourceStructVariable {
+    constructor(struct, astNode) {
+        this.struct = struct;
+        this.astNode = astNode;
+    }
+    get name() {
+        return this.astNode.name;
+    }
+    get type() {
+        return this.astNode.typeName.typeDescriptions.typeString;
+    }
+}
+class SourceFunction extends SourceFunctionLike {
     constructor(contract, astNode) {
@@ -291,3 +346,3 @@ super(contract);
 ], SourceFunction.prototype, "outputs", null);
-class SourceEvent extends SourceContractItem {
+class SourceEvent extends SourceFunctionLike {
     constructor(contract, astNode) {
@@ -298,3 +353,3 @@ super(contract);
 }
-class SourceModifier extends SourceContractItem {
+class SourceModifier extends SourceFunctionLike {
     constructor(contract, astNode) {
@@ -305,2 +360,34 @@ super(contract);
 }
+class SourceStruct extends SourceContractItem {
+    constructor(contract, astNode) {
+        super(contract);
+        this.astNode = astNode;
+    }
+    get members() {
+        return this.astNode.members.map(m => new SourceStructVariable(this, m));
+    }
+    get natspec() {
+        warnStateVariableNatspec();
+        return {};
+    }
+}
+__decorate([
+    memoize_1.memoize
+], SourceStruct.prototype, "members", null);
+class SourceEnum extends SourceContractItem {
+    constructor(contract, astNode) {
+        super(contract);
+        this.astNode = astNode;
+    }
+    get members() {
+        return this.astNode.members.map(m => m.name);
+    }
+    get natspec() {
+        warnStateVariableNatspec();
+        return {};
+    }
+}
+__decorate([
+    memoize_1.memoize
+], SourceEnum.prototype, "members", null);
 class SourceTypedVariable {
@@ -422,2 +509,8 @@ constructor(typeNode, name) {
 }
+function isStructDefinition(node) {
+    return node.nodeType == 'StructDefinition';
+}
+function isEnumDefinition(node) {
+    return node.nodeType == 'EnumDefinition';
+}
 function isContractDefinition(node) {
@@ -438,3 +531,3 @@ return node.nodeType === 'ContractDefinition';
 }
-const warnStateVariableNatspec = oneTimeLogger('Warning: NatSpec is currently not available for state variables.');
+const warnStateVariableNatspec = oneTimeLogger('Warning: NatSpec is currently not available for state variables, structs, or enums.');
 //# sourceMappingURL=source.js.map

package.json

 {
   "name": "solidity-docgen",
-  "version": "0.5.13",
+  "version": "0.5.14",
   "description": "Solidity API documentation automatic generator.",
@@ -22,4 +22,4 @@ "repository": "github:OpenZeppelin/solidity-docgen",
     "test:watch": "fgbg 'ava --watch' 'tsc --watch' --",
-    "prepublish": "rimraf dist tsconfig.tsbuildinfo",
-    "prepare": "yarn build"
+    "clean": "rimraf dist tsconfig.tsbuildinfo",
+    "prepare": "yarn clean && yarn build"
   },
@@ -41,3 +41,3 @@ "dependencies": {
   "devDependencies": {
-    "@ava/typescript": "^1.1.1",
+    "@ava/typescript": "^2.0.0",
     "@openzeppelin/contracts": "^4.0.0",
@@ -44,0 +44,0 @@ "@types/json5": "0.0.30",

src/cli.test.ts.md

@@ -29,2 +29,4 @@ # Snapshot report for `src/cli.test.ts`
     ␊
+    ␊
+    ␊
     ## \`Foo\`␊
@@ -53,4 +55,32 @@ ␊
     ␊
+    ␊
+    ␊
     `
 
+## fixture custom
+
+> Snapshot 1
+
+    `Foo␊
+    ␊
+    ### devdoc␊
+    ␊
+    dev docs␊
+    ␊
+    ␊
+    ### userdoc␊
+    ␊
+    user docs␊
+    ␊
+    ### custom a␊
+    ␊
+    first␊
+    ␊
+    ␊
+    ### custom b␊
+    ␊
+    second␊
+    ␊
+    `
+
 ## fixture dependencies
@@ -69,5 +99,5 @@
     Sets the values for {name} and {symbol}.␊
-    The defaut value of {decimals} is 18. To select a different value for␊
+    The default value of {decimals} is 18. To select a different value for␊
     {decimals} you should overload it.␊
-    All three of these values are immutable: they can only be set once during␊
+    All two of these values are immutable: they can only be set once during␊
     construction.␊
@@ -91,3 +121,3 @@ ␊
     Ether and Wei. This is the value {ERC20} uses, unless this function is␊
-    overloaded;␊
+    overridden;␊
     NOTE: This information is only used for _display_ purposes: it in␊
@@ -155,4 +185,4 @@ no way affects any of the arithmetic of the contract, including␊
     ␊
-    Moves tokens \`amount\` from \`sender\` to \`recipient\`.␊
-    This is internal function is equivalent to {transfer}, and can be used to␊
+    Moves \`amount\` of tokens from \`sender\` to \`recipient\`.␊
+    This internal function is equivalent to {transfer}, and can be used to␊
     e.g. implement automatic token fees, slashing mechanisms, etc.␊
@@ -171,3 +201,3 @@ Emits a {Transfer} event.␊
     Requirements:␊
-    - \`to\` cannot be the zero address.␊
+    - \`account\` cannot be the zero address.␊
     ␊
@@ -199,3 +229,3 @@ ## _burn␊
     - when \`from\` and \`to\` are both non-zero, \`amount\` of \`\`from\`\`'s tokens␊
-    will be to transferred to \`to\`.␊
+    will be transferred to \`to\`.␊
     - when \`from\` is zero, \`amount\` tokens will be minted for \`to\`.␊
@@ -206,2 +236,14 @@ - when \`to\` is zero, \`amount\` of \`\`from\`\`'s tokens will be burned.␊
     ␊
+    ## _afterTokenTransfer␊
+    ␊
+    Hook that is called after any transfer of tokens. This includes␊
+    minting and burning.␊
+    Calling conditions:␊
+    - when \`from\` and \`to\` are both non-zero, \`amount\` of \`\`from\`\`'s tokens␊
+    has been transferred to \`to\`.␊
+    - when \`from\` is zero, \`amount\` tokens have been minted for \`to\`.␊
+    - when \`to\` is zero, \`amount\` of \`\`from\`\`'s tokens have been burned.␊
+    - \`from\` and \`to\` are never both zero.␊
+    To learn more about hooks, head to xref:ROOT:extending-contracts.adoc#using-hooks[Using Hooks].␊
+    ␊
     ## _msgSender␊
@@ -269,2 +311,4 @@ ␊
     ␊
+    ␊
+    ␊
     ## \`Foo\`␊
@@ -284,28 +328,23 @@ ␊
     ␊
+    ␊
+    ␊
     `
 
-## fixture custom
+## fixture struct-enum
 
 > Snapshot 1
 
-    `Foo␊
+    `### \`Bar\`␊
     ␊
-    ### devdoc␊
+    - uint256 foo␊
+    - string bar␊
     ␊
-    dev docs␊
     ␊
+    ### \`Foo\`␊
     ␊
-    ### userdoc␊
+    All members: FOO,BAR␊
     ␊
-    user docs␊
+      - FOO␊
+      - BAR␊
     ␊
-    ### custom a␊
-    ␊
-    first␊
-    ␊
-    ␊
-    ### custom b␊
-    ␊
-    second␊
-    ␊
     `

src/solc.ts

@@ -49,3 +49,3 @@ import { fromPairs, pick } from 'lodash';
 
-  export type ContractItem = VariableDeclaration | FunctionDefinition | EventDefinition | ModifierDefinition;
+  export type ContractItem = VariableDeclaration | FunctionDefinition | EventDefinition | ModifierDefinition | StructDefinition | EnumDefinition;
 
@@ -84,2 +84,21 @@ export interface VariableDeclaration {
 
+  export interface StructDefinition {
+    nodeType: 'StructDefinition';
+    name: string;
+    members: VariableDeclaration[];
+    visibility: 'internal' | 'external' | 'public' | 'private';
+  }
+
+  export interface EnumDefinition {
+    nodeType: 'EnumDefinition';
+    name: string;
+    members: EnumValue[];
+  }
+
+  export interface EnumValue {
+    nodeType: 'EnumValue';
+    id: number;
+    name: string;
+  }
+
   export interface ParameterList {
@@ -86,0 +105,0 @@ parameters: {

src/source.ts

@@ -130,3 +130,11 @@ import { flatten, uniqBy, groupBy, defaults } from 'lodash';
   get linkable(): Linkable[] {
-    return [this, ...this.ownModifiers, ...this.ownVariables, ...this.ownFunctions, ...this.ownEvents];
+    return [
+      this,
+      ...this.ownModifiers,
+      ...this.ownVariables,
+      ...this.ownFunctions,
+      ...this.ownEvents,
+      ...this.ownStructs,
+      ...this.ownEnums,
+    ];
   }
@@ -181,2 +189,4 @@
     const modifiers = groupBy(this.modifiers, f => f.contract.astId);
+    const structs = groupBy(this.structs, f => f.contract.astId);
+    const enums = groupBy(this.enums, f => f.contract.astId);
 
@@ -189,2 +199,4 @@ return this.inheritance.map(contract => ({
       modifiers: modifiers[contract.astId],
+      structs: structs[contract.astId],
+      enums: enums[contract.astId],
     }));
@@ -221,3 +233,25 @@ }
 
+  get structs(): SourceStruct[] {
+    return flatten(this.inheritance.map(c => c.ownStructs));
+  }
+
   @memoize
+  get ownStructs(): SourceStruct[] {
+    return this.astNode.nodes
+      .filter(isStructDefinition)
+      .map(n => new SourceStruct(this, n))
+  }
+
+  get enums(): SourceEnum[] {
+    return flatten(this.inheritance.map(c => c.ownEnums));
+  }
+
+  @memoize
+  get ownEnums(): SourceEnum[] {
+    return this.astNode.nodes
+      .filter(isEnumDefinition)
+      .map(n => new SourceEnum(this, n))
+  }
+
+  @memoize
   get natspec(): NatSpec {
@@ -237,2 +271,4 @@ if (this.astNode.documentation === null || this.astNode.documentation === undefined) {
 abstract class SourceContractItem implements Linkable {
+  protected abstract astNode: Exclude<ast.ContractItem, ast.VariableDeclaration>;
+
   constructor(
@@ -242,4 +278,2 @@ readonly contract: SourceContract,
 
-  protected abstract astNode: Exclude<ast.ContractItem, ast.VariableDeclaration>;
-
   get name(): string {
@@ -254,2 +288,16 @@ return this.astNode.name;
   get anchor(): string {
+    return `${this.contract.name}-${this.name}`;
+  }
+}
+
+abstract class SourceFunctionLike extends SourceContractItem {
+  protected abstract astNode: ast.FunctionDefinition | ast.ModifierDefinition | ast.EventDefinition;
+
+  constructor(
+    readonly contract: SourceContract,
+  ) {
+    super(contract);
+  }
+
+  get anchor(): string {
     return `${this.contract.name}-${slug(this.signature)}`;
@@ -311,4 +359,19 @@ }
 
-class SourceFunction extends SourceContractItem {
+class SourceStructVariable {
   constructor(
+    readonly struct: SourceStruct,
+    protected readonly astNode: ast.VariableDeclaration,
+  ) { }
+
+  get name(): string {
+    return this.astNode.name;
+  }
+
+  get type(): string {
+    return this.astNode.typeName.typeDescriptions.typeString;
+  }
+}
+
+class SourceFunction extends SourceFunctionLike {
+  constructor(
     contract: SourceContract,
@@ -347,3 +410,3 @@ protected readonly astNode: ast.FunctionDefinition,
 
-class SourceEvent extends SourceContractItem {
+class SourceEvent extends SourceFunctionLike {
   constructor(
@@ -357,3 +420,3 @@ contract: SourceContract,
 
-class SourceModifier extends SourceContractItem {
+class SourceModifier extends SourceFunctionLike {
   constructor(
@@ -367,2 +430,40 @@ contract: SourceContract,
 
+class SourceStruct extends SourceContractItem {
+  constructor(
+    contract: SourceContract,
+    protected readonly astNode: ast.StructDefinition,
+  ) {
+    super(contract);
+  }
+
+  @memoize
+  get members(): SourceStructVariable[] {
+    return this.astNode.members.map(m => new SourceStructVariable(this, m));
+  }
+
+  get natspec(): {} {
+    warnStateVariableNatspec();
+    return {}
+  }
+}
+
+class SourceEnum extends SourceContractItem {
+  constructor(
+    contract: SourceContract,
+    protected readonly astNode: ast.EnumDefinition,
+  ) {
+    super(contract);
+  }
+
+  @memoize
+  get members(): string[] {
+    return this.astNode.members.map(m => m.name);
+  }
+
+  get natspec(): {} {
+    warnStateVariableNatspec();
+    return {}
+  }
+}
+
 class SourceTypedVariable {
@@ -398,2 +499,4 @@ constructor(
   modifiers: SourceModifier[];
+  structs: SourceStruct[];
+  enums: SourceEnum[];
 }
@@ -445,3 +548,3 @@
 
-function parseNatSpec(doc: string, context: SourceContractItem | SourceContract): NatSpec {
+function parseNatSpec(doc: string, context: SourceFunctionLike | SourceContract): NatSpec {
   const res: NatSpec = {};
@@ -540,2 +643,10 @@
 
+function isStructDefinition(node: ast.ContractItem): node is ast.StructDefinition {
+  return node.nodeType == 'StructDefinition';
+}
+
+function isEnumDefinition(node: ast.ContractItem): node is ast.EnumDefinition {
+  return node.nodeType == 'EnumDefinition';
+}
+
 function isContractDefinition(node: ast.SourceItem): node is ast.ContractDefinition {
@@ -560,2 +671,2 @@ return node.nodeType === 'ContractDefinition';
 
-const warnStateVariableNatspec = oneTimeLogger('Warning: NatSpec is currently not available for state variables.');
+const warnStateVariableNatspec = oneTimeLogger('Warning: NatSpec is currently not available for state variables, structs, or enums.');

No alert changes

Improved metrics

Total package byte prevSize

227000

increased by5.72%

Lines of code

4077

increased by6.5%

No dependency changes