Code style & inspection fixes (#6)

* code inspection fixes

* code inspection fixes

* happy linter - happy life

* added doc strings, cleaned up unused files

* added doc strings, cleaned up unused files

* docs generation

* tracer and docs generation config

* elaborated changeset

* happy linter - happy life

* notes and gas improvements

.changeset/spotty-beers-happen.md

@@ -0,0 +1,11 @@
+---
+"@peeramid-labs/eds": patch
+---
+
+### Changes
+
+- Added documentation strings.
+- Made minor logic improvements.
+- Implemented documentation generation from docstrings.
+- Performed gas optimizations.
+- Unified code style.

.gitignore

@@ -275,4 +275,5 @@ types
 
 
 abi/
-.secrets/
+.secrets/
+docs/contracts

docs/templates/common.hbs

@@ -0,0 +1,39 @@
+
+{{#if (isVisible visibility)}}
+{{h 2}}  {{name}}
+
+{{substituteAnchors natspec.notice}}
+
+{{#if signature}}
+```solidity
+{{{signature}}}
+```
+{{/if}}
+{{/if}}
+
+{{#if natspec.params}}
+| Input | Type | Description |
+|:----- | ---- | ----------- |
+{{#each params}}
+| `{{{name}}}` | `{{{type}}}` | {{{joinLines (substituteAnchors natspec)}}} |
+{{/each}}
+{{#if natspec.returns}}
+| **Output** | |
+{{#each returns}}
+| {{#if name}} `{{name}}` {{else}} `{{@index}}` {{/if}} | `{{type}}` | {{{joinLines (substituteAnchors natspec)}}} |
+{{/each}}
+{{/if}}
+{{else}}
+{{#if natspec.returns}}
+| Output | Type | Description |
+| ------ | ---- | ----------- |
+{{#each returns}}
+| {{#if name}} `{{{name}}}` {{else}} `{{{@index}}}` {{/if}} | `{{type}}` | {{{joinLines (substituteAnchors natspec)}}} |
+{{/each}}
+{{/if}}
+{{/if}}
+
+{{#if natspec.dev}}
+{{{transformDev (substituteAnchors natspec.dev)}}}
+{{/if}}
+

docs/templates/contract.hbs

@@ -0,0 +1,9 @@
+{{{natspec.notice}}}
+
+{{{transformDev (substituteAnchors natspec.dev)}}}
+
+
+{{#each items}}
+{{>item}}
+{{/each}}
+<!--CONTRACT_END-->

docs/templates/enum.hbs

@@ -0,0 +1,9 @@
+{{>common}}
+
+```solidity
+enum {{name}} {
+{{#each members}}
+  {{name}}{{#unless @last}},{{/unless}}
+{{/each}}
+}
+```

docs/templates/error.hbs

@@ -0,0 +1 @@
+{{>common}}

docs/templates/event.hbs

@@ -0,0 +1 @@
+{{>common}}

docs/templates/function.hbs

@@ -0,0 +1 @@
+{{>common}}

docs/templates/helpers.ts

@@ -0,0 +1,134 @@
+import { HelperOptions, Utils } from "handlebars";
+
+/**
+ * Returns a Markdown heading marker. An optional number increases the heading level.
+ *
+ *    Input                  Output
+ *    {{h}} {{name}}         # Name
+ *    {{h 2}} {{name}}       ## Name
+ */
+export function h(opts: HelperOptions): string;
+export function h(hsublevel: number, opts: HelperOptions): string;
+export function h(hsublevel: number | HelperOptions, opts?: HelperOptions) {
+  const { hlevel } = getHLevel(hsublevel, opts);
+  return new Array(hlevel).fill("#").join("");
+}
+
+/**
+ * Delineates a section where headings should be increased by 1 or a custom number.
+ *
+ *    {{#hsection}}
+ *    {{>partial-with-headings}}
+ *    {{/hsection}}
+ */
+export function hsection(opts: HelperOptions): string;
+export function hsection(hsublevel: number, opts: HelperOptions): string;
+export function hsection(this: unknown, hsublevel: number | HelperOptions, opts?: HelperOptions) {
+  let hlevel;
+  ({ hlevel, opts } = getHLevel(hsublevel, opts));
+  opts.data = Utils.createFrame(opts.data);
+  opts.data.hlevel = hlevel;
+  return opts.fn(this as unknown, opts);
+}
+
+/**
+ * Helper for dealing with the optional hsublevel argument.
+ */
+function getHLevel(hsublevel: number | HelperOptions, opts?: HelperOptions) {
+  if (typeof hsublevel === "number") {
+    opts = opts!;
+    hsublevel = Math.max(1, hsublevel);
+  } else {
+    opts = hsublevel;
+    hsublevel = 1;
+  }
+  const contextHLevel: number = opts.data?.hlevel ?? 0;
+  return { opts, hlevel: contextHLevel + hsublevel };
+}
+
+export function trim(text: string) {
+  if (typeof text === "string") {
+    return text.trim();
+  }
+}
+
+export function toLowerCase(text: string) {
+  return text.toLowerCase();
+}
+
+export function joinLines(text?: string) {
+  if (typeof text === "string") {
+    return text.replace(/\n+/g, " ");
+  }
+}
+
+export function transformDev(comment: string): string {
+  // Split the comment into lines
+  const lines = comment?.split("\n") ?? [];
+
+  // Initialize variables to store the transformed text
+  let transformedText = "";
+  let isWarning = false;
+  let isFirstNotice = true;
+  let noticeBlock = "";
+
+  // Iterate over each line
+  lines.forEach((line) => {
+    const trimmedLine = line.trim();
+
+    // Check if the line starts with WARNING:
+    if (trimmedLine.startsWith("WARNING:")) {
+      // Add the WARNING prefix
+      if (noticeBlock) {
+        transformedText += `\n\n!!! NOTICE\n\n\t${noticeBlock.trim().replace(/\n/g, "\n\t")}`;
+        noticeBlock = "";
+      }
+      transformedText += `\n\n!!! WARNING\n\n\t${trimmedLine.replace("WARNING:", "").trim()}`;
+      isWarning = true;
+    } else if (trimmedLine) {
+      // Add the line to the NOTICE block
+      if (isWarning) {
+        transformedText += `\n\t${trimmedLine}`;
+      } else {
+        noticeBlock += `\n${trimmedLine}`;
+      }
+    } else {
+      // Handle empty lines
+      if (noticeBlock) {
+        transformedText += `\n\n!!! NOTICE\n\n\t${noticeBlock.trim().replace(/\n/g, "\n\t")}`;
+        noticeBlock = "";
+      }
+      isWarning = false;
+    }
+  });
+
+  // Add any remaining notice block
+  if (noticeBlock) {
+    transformedText += `\n\n!!! NOTICE\n\n\t${noticeBlock.trim().replace(/\n/g, "\n\t")}`;
+  }
+
+  // Return the transformed text
+  return transformedText.trim();
+}
+
+export const isVisible = (type: string) => {
+  return type !== "internal" && type !== "private";
+};
+
+export const substituteAnchors = (text: string) => {
+  if (typeof text === "string") {
+    return text.replace(/{([^}]+)}/g, (match: string, p1: string) => {
+      // Split the reference into parts
+      const parts = p1.split(".");
+      const anchor = parts.length > 1 ? `#${parts.slice(1).join(".").toLocaleLowerCase()}` : "";
+      const reference = parts[0];
+      const displayText = reference.charAt(0).toUpperCase() + reference.slice(1);
+
+      // Handle different depth levels
+      const path = reference.startsWith("../") ? reference : `./${reference}`;
+
+      return `[${displayText}${anchor}](../${path}${anchor})`;
+    });
+  }
+  return text;
+};

docs/templates/modifier.hbs

@@ -0,0 +1 @@
+{{>common}}

docs/templates/page.hbs

@@ -0,0 +1,8 @@
+
+{{#each items}}
+{{h 1}} {{{natspec.title}}}
+{{#hsection}}
+{{>item}}
+{{/hsection}}
+
+{{/each}}

docs/templates/struct.hbs

@@ -0,0 +1,9 @@
+{{>common}}
+
+```solidity
+struct {{name}} {
+{{#each members}}
+  {{{typeName.typeDescriptions.typeString}}} {{name}};
+{{/each}}
+}
+```

docs/templates/user-defined-value-type.hbs

@@ -0,0 +1 @@
+{{>common}}

docs/templates/variable.hbs

@@ -0,0 +1 @@
+{{>common}}

hardhat.config.ts

@@ -6,6 +6,7 @@ import "hardhat-gas-reporter";
 import "hardhat-contract-sizer";
 import "hardhat-deploy";
 import "solidity-docgen";
+import "hardhat-tracer";
 // import "@nomicfoundation/hardhat-verify";
 task("accounts", "Prints the list of accounts", async (taskArgs, hre) => {
   const accounts = await hre.ethers.getSigners();
@@ -18,7 +19,8 @@ task("accounts", "Prints the list of accounts", async (taskArgs, hre) => {
 export default {
   docgen: {
     outputDir: "./docs/contracts",
-    pages: "single",
+    pages: "files",
+    templates: "docs/templates",
     sourcesDir: "./src",
     pageExtension: ".md",
     exclude: ["mocks", "initializers", "vendor", "modifiers", "fixtures"],

package.json

@@ -55,6 +55,7 @@
     "hardhat-abi-exporter": "^2.9.0",
     "hardhat-contract-sizer": "^2.6.1",
     "hardhat-deploy": "^0.12.2",
+    "hardhat-tracer": "^3.1.0",
     "keccak": "^3.0.1",
     "mocha": "^10.0.0",
     "prettier-plugin-solidity": "^1.4.1",

src/abstracts/CloneDistribution.sol

@@ -6,24 +6,28 @@ import "../interfaces/IDistribution.sol";
 import "./CodeIndexer.sol";
 
 abstract contract CloneDistribution is IDistribution, CodeIndexer {
-
+    error CodeNotFoundInIndex(bytes32 codeId);
 
     function sources() internal view virtual returns (address[] memory, bytes32 name, uint256 version);
 
-    function instantiate(bytes memory) public virtual returns (address[] memory instances, bytes32 distributionName, uint256 distributionVersion) {
-        (address[] memory _sources,bytes32 _distributionName,uint256 _distributionVersion) = sources();
-        instances = new address[](_sources.length);
-        for (uint256 i = 0; i < _sources.length; i++) {
+    // @inheritdoc IDistribution
+    function instantiate(
+        bytes memory
+    ) external virtual returns (address[] memory instances, bytes32 distributionName, uint256 distributionVersion) {
+        (address[] memory _sources, bytes32 _distributionName, uint256 _distributionVersion) = sources();
+        uint256 srcsLength = _sources.length;
+        instances = new address[](srcsLength);
+        for (uint256 i; i < srcsLength; ++i) {
             address clone = Clones.clone(_sources[i]);
             instances[i] = clone;
         }
         emit Distributed(msg.sender, instances);
         return (instances, _distributionName, _distributionVersion);
     }
-
-    function get() public view virtual returns (address[] memory src, bytes32 name, uint256 version) {
+    // @inheritdoc IDistribution
+    function get() external view virtual returns (address[] memory src, bytes32 name, uint256 version) {
         return sources();
     }
-
-    function getMetadata() public view virtual returns (string memory);
+    // @inheritdoc IDistribution
+    function getMetadata() external view virtual returns (string memory);
 }