Re-adds jsdoc, add a few ignores for code that should not be exposed …

…via the programmatic API. #3060

.gitignore

@@ -7,6 +7,7 @@ node_modules/
 # Ignore build tool output, e.g. code coverage
 .nyc_output/
 coverage/
+jsdoc/
 
 # Ignore API documentation
 api-docs/

.npmignore

@@ -1,5 +1,6 @@
+jsdoc
 docs
 docs-src
 test
 coverage
-.*
+.*

package.json

@@ -38,6 +38,7 @@
   ],
   "scripts": {
     "default": "npm run test",
+    "jsdoc": "rm -rf jsdoc && npx jsdoc src/* -r -d jsdoc",
     "format": "prettier . --write",
     "test": "npx ava --verbose",
     "lint-staged": "lint-staged",
@@ -80,6 +81,7 @@
     "ava": "^5.3.1",
     "husky": "^8.0.3",
     "js-yaml": "^4.1.0",
+    "jsdoc": "^4.0.2",
     "lint-staged": "^15.0.2",
     "markdown-it-emoji": "^2.0.2",
     "marked": "^9.1.5",

src/Eleventy.js

@@ -34,8 +34,8 @@ const debug = debugUtil("Eleventy");
 /**
  * Runtime of eleventy.
  *
- * @param {String} input - Where to read files from.
- * @param {String} output - Where to write rendered files to.
+ * @param {String} input - Directory or filename for input/sources files.
+ * @param {String} output - Directory serving as the target for writing the output files.
  * @returns {module:11ty/eleventy/Eleventy~Eleventy}
  */
 class Eleventy {
@@ -46,7 +46,7 @@ class Eleventy {
     /** @member {String} - Holds the path to the output directory. */
     this.rawOutput = output;
 
-    /** @member {TemplateConfig} - Override the config instance (for centralized config re-use) */
+    /** @member {module:11ty/eleventy/TemplateConfig} - Override the config instance (for centralized config re-use) */
     this.eleventyConfig = eleventyConfig;
 
     /**
@@ -99,7 +99,7 @@ class Eleventy {
 
     /**
      * @member {Boolean} - Is this an incremental build? (only operates on a subset of input files)
-     * @default null
+     * @default false
      */
     this.isIncremental = false;
 
@@ -111,13 +111,14 @@ class Eleventy {
 
     /**
      * @member {Boolean} - Should we process files on first run? (The --ignore-initial feature)
-     * @default null
+     * @default true
      */
     this.isRunInitialBuild = true;
 
     /**
      * @member {Boolean} - Has the async initialization for config run yet?
-     * @default null
+     * @private
+     * @default false
      */
     this._hasConfigInitialized = false;
   }
@@ -1294,7 +1295,16 @@ export default Eleventy;
 
 export {
   Eleventy,
+  /**
+   * @type {module:11ty/eleventy/Plugins/RenderPlugin}
+   */
   RenderPlugin as EleventyRenderPlugin,
+  /**
+   * @type {module:11ty/eleventy/Plugins/I18nPlugin}
+   */
   I18nPlugin as EleventyI18nPlugin,
+  /**
+   * @type {module:11ty/eleventy/Plugins/HtmlBasePlugin}
+   */
   HtmlBasePlugin as EleventyHtmlBasePlugin,
 };

src/EleventyBaseError.js

@@ -1,5 +1,6 @@
 /**
  * This class serves as basis for all Eleventy-specific errors.
+ * @ignore
  */
 class EleventyBaseError extends Error {
   /**
@@ -9,13 +10,11 @@ class EleventyBaseError extends Error {
   constructor(message, originalError) {
     super(message);
 
-    /** @type {string} - The error message to display. */
     this.name = this.constructor.name;
 
     Error.captureStackTrace(this, this.constructor);
 
     if (originalError) {
-      /** @type {Error} - The original error caught. */
       this.originalError = originalError;
     }
   }

src/EventBus.js

@@ -6,13 +6,14 @@ const debug = debugUtil("Eleventy:EventBus");
 
 /**
  * @module 11ty/eleventy/EventBus
+ * @ignore
  */
 
 debug("Setting up global EventBus.");
 /**
  * Provides a global event bus that modules deep down in the stack can
  * subscribe to from a global singleton for decoupled pub/sub.
- * @type * {module:11ty/eleventy/Util/AsyncEventEmitter~AsyncEventEmitter}
+ * @type {module:11ty/eleventy/Util/AsyncEventEmitter~AsyncEventEmitter}
  */
 let bus = new EventEmitter();
 bus.setMaxListeners(100);

src/Plugins/RenderPlugin.js

@@ -51,7 +51,7 @@ async function compile(content, templateLang, { templateConfig, extensionMap } =
     tr.engine.name === "11ty.mjs"
   ) {
     throw new Error(
-      "11ty.js is not yet supported as a template engine for `renderTemplate`. Use `renderFile` instead!"
+      "11ty.js is not yet supported as a template engine for `renderTemplate`. Use `renderFile` instead!",
     );
   }
 
@@ -66,7 +66,7 @@ async function compileFile(inputPath, { templateConfig, extensionMap, config } =
 
   if (!(await fsExists(TemplatePath.normalizeOperatingSystemFilePath(inputPath)))) {
     throw new Error(
-      "Could not find render plugin file for the `renderFile` shortcode, looking for: " + inputPath
+      "Could not find render plugin file for the `renderFile` shortcode, looking for: " + inputPath,
     );
   }
 
@@ -128,16 +128,33 @@ async function renderShortcodeFn(fn, data) {
   return fn(data);
 }
 
+/**
+ * @module 11ty/eleventy/Plugins/RenderPlugin
+ */
+
+/**
+ * A plugin to add shortcodes to render an Eleventy template
+ * string (or file) inside of another template. {@link https://www.11ty.dev/docs/plugins/render/}
+ *
+ * @since 1.0.0
+ * @param {module:11ty/eleventy/UserConfig} eleventyConfig - User-land configuration instance.
+ * @param {Object} options - Plugin options
+ */
 function EleventyPlugin(eleventyConfig, options = {}) {
-  let opts = Object.assign(
-    {
-      tagName: "renderTemplate",
-      tagNameFile: "renderFile",
-      templateConfig: null,
-      accessGlobalData: false,
-    },
-    options
-  );
+  /**
+   * @typedef {Object} options
+   * @property {string} [tagName] - The shortcode name to render a template string.
+   * @property {string} [tagNameFile] - The shortcode name to render a template file.
+   * @property {module:11ty/eleventy/TemplateConfig} [templateConfig] - Configuration object
+   * @property {boolean} [accessGlobalData] - Whether or not the template has access to the page’s data.
+   */
+  let defaultOptions = {
+    tagName: "renderTemplate",
+    tagNameFile: "renderFile",
+    templateConfig: null,
+    accessGlobalData: false,
+  };
+  let opts = Object.assign(defaultOptions, options);
 
   function liquidTemplateTag(liquidEngine, tagName) {
     // via https://github.com/harttle/liquidjs/blob/b5a22fa0910c708fe7881ef170ed44d3594e18f3/src/builtin/tags/raw.ts
@@ -186,7 +203,7 @@ function EleventyPlugin(eleventyConfig, options = {}) {
           normalizedContext,
           body,
           // templateLang, data
-          ...argArray
+          ...argArray,
         );
         yield ret;
         return ret;
@@ -210,7 +227,7 @@ function EleventyPlugin(eleventyConfig, options = {}) {
         const endTagName = "end" + tagName;
         // Look for upcoming raw blocks (ignore all other kinds of blocks)
         const rawBlockRegex = new RegExp(
-          "([\\s\\S]*?){%\\s*(" + tagName + "|" + endTagName + ")\\s*(?=%})%}"
+          "([\\s\\S]*?){%\\s*(" + tagName + "|" + endTagName + ")\\s*(?=%})%}",
         );
         let rawLevel = 1;
         let str = "";
@@ -270,9 +287,9 @@ function EleventyPlugin(eleventyConfig, options = {}) {
             resolve(
               new EleventyShortcodeError(
                 `Error with Nunjucks paired shortcode \`${tagName}\`${EleventyErrorUtil.convertErrorToString(
-                  e
-                )}`
-              )
+                  e,
+                )}`,
+              ),
             );
           }
 
@@ -281,8 +298,8 @@ function EleventyPlugin(eleventyConfig, options = {}) {
               normalizedContext,
               bodyContent,
               // templateLang, data
-              ...argArray
-            )
+              ...argArray,
+            ),
           )
             .then(function (returnValue) {
               resolve(null, new NunjucksLib.runtime.SafeString(returnValue));
@@ -291,10 +308,10 @@ function EleventyPlugin(eleventyConfig, options = {}) {
               resolve(
                 new EleventyShortcodeError(
                   `Error with Nunjucks paired shortcode \`${tagName}\`${EleventyErrorUtil.convertErrorToString(
-                    e
-                  )}`
+                    e,
+                  )}`,
                 ),
-                null
+                null,
               );
             });
         });
@@ -337,7 +354,7 @@ function EleventyPlugin(eleventyConfig, options = {}) {
         templateConfig: opts.templateConfig || templateConfig,
         extensionMap,
       },
-      templateLang
+      templateLang,
     );
 
     return renderShortcodeFn.call(this, fn, data);

src/TemplateConfig.js

@@ -32,17 +32,19 @@ const debugDev = debugUtil("Dev:Eleventy:TemplateConfig");
 
 /**
  * Errors in eleventy config.
+ * @ignore
  */
 class EleventyConfigError extends EleventyBaseError {}
 
 /**
  * Errors in eleventy plugins.
+ * @ignore
  */
 class EleventyPluginError extends EleventyBaseError {}
 
 /**
  * Config for a template.
- *
+ * @ignore
  * @param {{}} customRootConfig - tbd.
  * @param {String} projectConfigPath - Path to local project config.
  */

src/UserConfig.js

@@ -15,7 +15,10 @@ class UserConfigError extends EleventyBaseError {}
 
 const ComparisonAsyncFunction = (async () => {}).constructor;
 
-// API to expose configuration options in config file
+/**
+ * API to expose configuration options in user-land configuration files
+ * @module 11ty/eleventy/UserConfig
+ */
 class UserConfig {
   constructor() {
     this._uniqueId = Math.random();

src/Util/AsyncEventEmitter.js

@@ -7,8 +7,8 @@ import EventEmitter from "node:events";
 class AsyncEventEmitter extends EventEmitter {
   /**
    * @param {string} type - The event name to emit.
-   * @param {*[]} args - Additional arguments that get passed to listeners.
-   * @returns {Promise<*[]>} - Promise resolves once all listeners were invoked
+   * @param {...*} args - Additional arguments that get passed to listeners.
+   * @returns {Promise} - Promise resolves once all listeners were invoked
    */
   async emit(type, ...args) {
     let listeners = this.listeners(type);
@@ -21,8 +21,8 @@ class AsyncEventEmitter extends EventEmitter {
 
   /**
    * @param {string} type - The event name to emit.
-   * @param {*[]} args - Additional lazy-executed function arguments that get passed to listeners.
-   * @returns {Promise<*[]>} - Promise resolves once all listeners were invoked
+   * @param {...*} args - Additional lazy-executed function arguments that get passed to listeners.
+   * @returns {Promise} - Promise resolves once all listeners were invoked
    */
   async emitLazy(type, ...args) {
     let listeners = this.listeners(type);

src/Util/ConsoleLogger.js

@@ -6,6 +6,7 @@ const debug = debugUtil("Eleventy:Logger");
 
 /**
  * Logger implementation that logs to STDOUT.
+ * @ignore
  */
 class ConsoleLogger {
   constructor() {