docs(Eleventy): add docstrings to Eleventy class.

Signed-off-by: André Jaenisch <[email protected]>
11ty · Jun 28, 2019 · 1d14e5d · 1d14e5d
1 parent 2cfedc7
commit 1d14e5d
Show file tree

Hide file tree

Showing 2 changed files with 153 additions and 6 deletions.
diff --git a/.jsdoc.conf.json b/.jsdoc.conf.json
@@ -1,11 +1,11 @@
 {
   "plugins": ["plugins/markdown"],
   "templates": {
-  	"systemName": "Eleventy",
-  	"theme": "cosmo",
-  	"navType": "vertical",
-  	"inverseNav": true,
-  	"syntaxTheme": "dark",
-  	"search": false
+    "systemName": "Eleventy",
+    "theme": "cosmo",
+    "navType": "vertical",
+    "inverseNav": true,
+    "syntaxTheme": "dark",
+    "search": false
   }
 }
diff --git a/src/Eleventy.js b/src/Eleventy.js
@@ -76,14 +76,17 @@ class Eleventy {
     this.watchTargets.watchJavaScriptDependencies = this.config.watchJavaScriptDependencies;
   }
 
+  /** @type {String} */
   get input() {
     return this.rawInput || this.config.dir.input;
   }
 
+  /** @type {String} */
   get inputDir() {
     return TemplatePath.getDir(this.input);
   }
 
+  /** @type {String} */
   get outputDir() {
     let dir = this.rawOutput || this.config.dir.output;
     if (dir !== this._savedOutputDir) {
@@ -94,25 +97,55 @@ class Eleventy {
     return dir;
   }
 
+  /**
+   * Updates the dry-run mode of Eleventy.
+   *
+   * @method
+   * @param {Boolean} isDryRun - Shall Eleventy run in dry mode?
+   */
   setDryRun(isDryRun) {
     this.isDryRun = !!isDryRun;
   }
 
+  /**
+   * Updates the passthrough mode of Eleventy.
+   *
+   * @method
+   * @param {Boolean} isPassthroughAll - Shall Eleventy passthrough everything?
+   */
   setPassthroughAll(isPassthroughAll) {
     this.isPassthroughAll = !!isPassthroughAll;
   }
 
+  /**
+   * Updates the path prefix used in the config.
+   *
+   * @method
+   * @param {String} pathPrefix - The new path prefix.
+   */
   setPathPrefix(pathPrefix) {
     if (pathPrefix || pathPrefix === "") {
       config.setPathPrefix(pathPrefix);
       this.config = config.getConfig();
     }
   }
 
+  /**
+   * Updates the watch targets.
+   *
+   * @method
+   * @param {} watchTargets - The new watch targets.
+   */
   setWatchTargets(watchTargets) {
     this.watchTargets = watchTargets;
   }
 
+  /**
+   * Updates the config path.
+   *
+   * @method
+   * @param {String} configPath - The new config path.
+   */
   setConfigPathOverride(configPath) {
     if (configPath) {
       this.configPath = configPath;
@@ -122,6 +155,12 @@ class Eleventy {
     }
   }
 
+  /**
+   * Restarts Eleventy.
+   *
+   * @async
+   * @method
+   */
   async restart() {
     debug("Restarting");
     this.start = new Date();
@@ -136,13 +175,24 @@ class Eleventy {
     await this.init();
   }
 
+  /**
+   * Marks the finish of a run of Eleventy.
+   *
+   * @method
+   */
   finish() {
     bench.finish();
 
     (this.logger || console).log(this.logFinished());
     debug("Finished writing templates.");
   }
 
+  /**
+   * Logs some statistics after a complete run of Eleventy.
+   *
+   * @method
+   * @returns {String} ret - The log message.
+   */
   logFinished() {
     if (!this.writer) {
       throw new Error(
@@ -184,6 +234,13 @@ class Eleventy {
     return ret.join(" ");
   }
 
+  /**
+   * Starts Eleventy.
+   *
+   * @async
+   * @method
+   * @returns {} - tbd.
+   */
   async init() {
     let formats = this.formatsOverride || this.config.templateFormats;
     this.eleventyFiles = new EleventyFiles(
@@ -222,10 +279,22 @@ Template Formats: ${formats.join(",")}`);
     return this.templateData.cacheData();
   }
 
+  /**
+   * Updates the debug mode of Eleventy.
+   *
+   * @method
+   * @param {Boolean} isDebug - Shall Eleventy run in debug mode?
+   */
   setIsDebug(isDebug) {
     this.isDebug = !!isDebug;
   }
 
+  /**
+   * Updates the verbose mode of Eleventy.
+   *
+   * @method
+   * @param {Boolean} isVerbose - Shall Eleventy run in verbose mode?
+   */
   setIsVerbose(isVerbose) {
     this.isVerbose = !!isVerbose;
 
@@ -237,16 +306,34 @@ Template Formats: ${formats.join(",")}`);
     }
   }
 
+  /**
+   * Updates the template formats of Eleventy.
+   *
+   * @method
+   * @param {String} formats - The new template formats.
+   */
   setFormats(formats) {
     if (formats && formats !== "*") {
       this.formatsOverride = formats.split(",");
     }
   }
 
+  /**
+   * Reads the version of Eleventy.
+   *
+   * @method
+   * @returns {String} - The version of Eleventy.
+   */
   getVersion() {
     return require("../package.json").version;
   }
 
+  /**
+   * Shows a help message including usage.
+   *
+   * @method
+   * @returns {String} - The help mesage.
+   */
   getHelp() {
     return `usage: eleventy
        eleventy --input=. --output=./_site
@@ -275,13 +362,25 @@ Arguments:
      --help`;
   }
 
+  /**
+   * Resets the config of Eleventy.
+   *
+   * @method
+   */
   resetConfig() {
     config.reset();
 
     this.config = config.getConfig();
     this.eleventyServe.config = this.config;
   }
 
+  /**
+   * tbd.
+   *
+   * @private
+   * @method
+   * @param {String} path - Watch this file.
+   */
   async _watch(path) {
     if (path) {
       path = TemplatePath.addLeadingDotSlash(path);
@@ -328,10 +427,21 @@ Arguments:
     }
   }
 
+  /**
+   * tbd.
+   *
+   * @returns {} - tbd.
+   */
   get watcherBench() {
     return bench.get("Watcher");
   }
 
+  /**
+   * Set up watchers and benchmarks.
+   *
+   * @async
+   * @method
+   */
   async initWatch() {
     this.watchTargets.add(this.eleventyFiles.getGlobWatcherFiles());
 
@@ -351,6 +461,13 @@ Arguments:
     benchmark.after();
   }
 
+  /**
+   * Starts watching dependencies.
+   *
+   * @private
+   * @async
+   * @method
+   */
   async _initWatchDependencies() {
     if (!this.watchTargets.watchJavaScriptDependencies) {
       return;
@@ -381,10 +498,23 @@ Arguments:
     );
   }
 
+  /**
+   * Returns all watched files.
+   *
+   * @async
+   * @method
+   * @returns {} targets - The watched files.
+   */
   async getWatchedFiles() {
     return this.watchTargets.getTargets();
   }
 
+  /**
+   * Start the watching of files.
+   *
+   * @async
+   * @method
+   */
   async watch() {
     this.watcherBench.setMinimumThresholdMs(500);
     this.watcherBench.reset();
@@ -448,15 +578,32 @@ Arguments:
     );
   }
 
+  /**
+   * Serve Eleventy on this port.
+   *
+   * @param {Number} port - The HTTP port to serve Eleventy from.
+   */
   serve(port) {
     this.eleventyServe.serve(port);
   }
 
   /* For testing */
+  /**
+   * Updates the logger.
+   *
+   * @param {} logger - The new logger.
+   */
   setLogger(logger) {
     this.logger = logger;
   }
 
+  /**
+   * tbd.
+   *
+   * @async
+   * @method
+   * @returns {Promise<{}>} ret - tbd.
+   */
   async write() {
     let ret;
     if (this.logger) {