feat: Add JSdoc for pfelement (#89) (#1520)

* feat: Add JSdoc for pfelement

* feat: Update changelog

* feat: Preserve example page

* feat: Remove compiled assets from commit

* feat: Remove commented out config and link to documentation

* feat: Update package; remove jsdoc for gulp-jsdoc3

* Update gulpfile.js

* Update gulpfile.factory.js

* Update gulpfile.factory.js

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: castastrophe

.gitignore

@@ -53,3 +53,5 @@ test/.wct-kludge
 
 # Sassdoc compiled assets ignored
 elements/pfe-sass/demo/*
+elements/pfelement/demo/*
+!elements/pfelement/demo/example.html

CHANGELOG-1.x.md

@@ -1,6 +1,7 @@
-# 1.5.2 (2021)
+# 1.6.0 (2021)
 
-- [](https://github.com/patternfly/patternfly-elements/commit/) fix: pfe-primary-detail IE11 rendering fix
+- [](https://github.com/patternfly/patternfly-elements/commit/) feat: JSDoc preview added for PFElement
+- [65983e6](https://github.com/patternfly/patternfly-elements/commit/65983e60d5394116d3dce6870b77f72772fa09c0) fix: pfe-primary-detail IE11 rendering fix
 
 # 1.5.1 (2021-04-15)
 

elements/pfe-sass/gulpfile.js

@@ -15,15 +15,15 @@ const paths = {
   temp: "./_temp"
 };
 
-const clean = require("gulp-clean");
+const del = require("del");
 const sassdoc = require("sassdoc");
 
 // Delete the demo assets
-task("clean", () => src(["demo/*.html", "demo/assets"], {
+task("clean", () => del(["demo/*.html", "demo/assets"], {
   cwd: paths.compiled,
   read: false,
   allowEmpty: true
-}).pipe(clean()));
+}));
 
 task("build:sassdoc", () => src(["{extends,functions,maps,mixins,variables}/_*.scss", "pfe-sass.scss"], {
   cwd: paths.compiled,

elements/pfelement/demo/index.html elements/pfelement/demo/example.htmlelements/pfelement/demo/index.html renamed to elements/pfelement/demo/example.html

@@ -1,4 +1,48 @@
 const gulpFactory = require("../../scripts/gulpfile.factory.js");
 const pfelementPackage = require("./package.json");
 
-gulpFactory(pfelementPackage);
+const { task, src, series } = require("gulp");
+const jsdoc = require("gulp-jsdoc3");
+const del = require("del");
+
+task("clean:jsdoc", () =>
+  del(["demo/**", "!demo/example.html"], {
+    read: false,
+    allowEmpty: true
+  })
+);
+
+task("build:jsdoc", cb => {
+  src(["README.md", "dist/pfelement.js"], {
+    read: false,
+    allowEmpty: true
+  }).pipe(
+    jsdoc(
+      {
+        opts: {
+          destination: "demo/",
+          template: "../../node_modules/foodoc/template"
+        },
+        // https://github.com/steveush/foodoc#configuring-the-template
+        templates: {
+          systemName: "PatternFly Elements",
+          systemSummary: "A set of community-created web components based on PatternFly design.",
+          systemLogo: "../../brand/logo/svg/pfe-icon-white-shaded.svg",
+          favicon: "../../brand/logo/svg/pfe-icon-blue-shaded.svg",
+          systemColor: "rgb(0, 64, 128)",
+          copyright: "©2021 Red Hat, Inc.",
+          includeDate: true,
+          dateFormat: "YYYY MMM DD",
+          showAccessFilter: false,
+          collapseSymbols: false,
+          stylesheets: ["../pfe-styles/dist/pfe-base.min.css"]
+        }
+      },
+      cb
+    )
+  );
+});
+
+task("jsdoc", series("clean:jsdoc", "build:jsdoc"));
+
+gulpFactory(Object.assign(pfelementPackage, { postbundle: ["jsdoc"] }));

elements/pfelement/gulpfile.js

@@ -1,9 +1,9 @@
 /**
  * Verify that a property definition's `type` field contains one of the allowed
- * types.
- *
- * Allowed types are String, Number, and Boolean.  If `type` is falsy, it
- * defaults to String.
+ * types.  If the definition type resolves to falsy, assumes String type.
+ * @param {constructor} definition
+ * @default String
+ * @return {Boolean} True if the definition type is one of String, Number, or Boolean
  */
 export function isAllowedType(definition) {
   return [String, Number, Boolean].includes(definition.type || String);
@@ -15,6 +15,8 @@ export function isAllowedType(definition) {
  * A `default` value is valid if it's of the same type as the `type`
  * definition.  Or, if there is no `type` definition, then it must be a String
  * (the default value for `type`).
+ * @param {type} definition
+ * @return {Boolean} True if the default value matches the type of the definition object.
  */
 export function isValidDefaultType(definition) {
   return definition.hasOwnProperty("default") && definition.default.constructor === definition.type;

elements/pfelement/src/attrDefValidators.js

@@ -3,13 +3,24 @@ import { isAllowedType, isValidDefaultType } from "./attrDefValidators.js";
 // Import polyfills: includes
 import "./polyfills--pfelement.js";
 
+// /**
+//  * Global prefix used for all components in the project.
+//  * @constant {String}
+//  * */
 const prefix = "pfe";
 
+/**
+ * @class PFElement
+ * @extends HTMLElement
+ * @version {{version}}
+ * @classdesc Serves as the baseline for all PatternFly Element components.
+ */
 class PFElement extends HTMLElement {
   /**
    * A boolean value that indicates if the logging should be printed to the console; used for debugging.
-   *
-   * @example In a JS file or script tag: `PFElement._debugLog = true;`
+   * For use in a JS file or script tag; can also be added in the constructor of a component during development.
+   * @example PFElement._debugLog = true;
+   * @tags debug
    */
   static debugLog(preference = null) {
     if (preference !== null) {
@@ -20,8 +31,8 @@ class PFElement extends HTMLElement {
 
   /**
    * A boolean value that indicates if the performance should be tracked.
-   *
-   * @example In a JS file or script tag: `PFElement._trackPerformance = true;`
+   * For use in a JS file or script tag; can also be added in the constructor of a component during development.
+   * @example PFElement._trackPerformance = true;
    */
   static trackPerformance(preference = null) {
     if (preference !== null) {
@@ -33,7 +44,7 @@ class PFElement extends HTMLElement {
   /**
    * A logging wrapper which checks the debugLog boolean and prints to the console if true.
    *
-   * @example `PFElement.log("Hello")`
+   * @example PFElement.log("Hello");
    */
   static log(...msgs) {
     if (PFElement.debugLog()) {
@@ -44,7 +55,7 @@ class PFElement extends HTMLElement {
   /**
    * Local logging that outputs the tag name as a prefix automatically
    *
-   * @example In a component's function: `this.log("Hello")`
+   * @example this.log("Hello");
    */
   log(...msgs) {
     PFElement.log(`[${this.tag}${this.id ? `#${this.id}` : ""}]: ${msgs.join(", ")}`);
@@ -53,34 +64,34 @@ class PFElement extends HTMLElement {
   /**
    * A console warning wrapper which formats your output with useful debugging information.
    *
-   * @example `PFElement.warn("Hello")`
+   * @example PFElement.warn("Hello");
    */
   static warn(...msgs) {
     console.warn(...msgs);
   }
 
   /**
    * Local warning wrapper that outputs the tag name as a prefix automatically.
-   *
-   * @example In a component's function: `this.warn("Hello")`
+   * For use inside a component's function.
+   * @example this.warn("Hello");
    */
   warn(...msgs) {
     PFElement.warn(`[${this.tag}${this.id ? `#${this.id}` : ``}]: ${msgs.join(", ")}`);
   }
 
   /**
    * A console error wrapper which formats your output with useful debugging information.
-   *
-   * @example `PFElement.error("Hello")`
+   * For use inside a component's function.
+   * @example PFElement.error("Hello");
    */
   static error(...msgs) {
     throw new Error([...msgs].join(" "));
   }
 
   /**
    * Local error wrapper that outputs the tag name as a prefix automatically.
-   *
-   * @example In a component's function: `this.error("Hello")`
+   * For use inside a component's function.
+   * @example this.error("Hello");
    */
   error(...msgs) {
     PFElement.error(`[${this.tag}${this.id ? `#${this.id}` : ``}]:`, ...msgs);
@@ -107,8 +118,8 @@ class PFElement extends HTMLElement {
 
   /**
    * A local alias to the static version.
-   *
-   * @example: In the console: `PfeAccordion.version`
+   * For use in the console to validate version being loaded.
+   * @example PfeAccordion.version
    */
   get version() {
     return this._pfeClass.version;
@@ -175,7 +186,7 @@ class PFElement extends HTMLElement {
    * A quick way to fetch a random ID value.
    * _Note:_ All values are prefixes with `pfe` automatically to ensure an ID-safe value is returned.
    *
-   * @example: In a component's JS: `this.id = this.randomID;`
+   * @example this.id = this.randomID;
    */
   get randomId() {
     return (
@@ -205,7 +216,7 @@ class PFElement extends HTMLElement {
   /**
    * Returns a boolean statement of whether or not this component contains any light DOM.
    * @returns {boolean}
-   * @examples `if(this.hasLightDOM()) this._init();`
+   * @example if(this.hasLightDOM()) this._init();
    */
   hasLightDOM() {
     return this.children.length || this.textContent.trim().length;
@@ -214,7 +225,7 @@ class PFElement extends HTMLElement {
   /**
    * Returns a boolean statement of whether or not that slot exists in the light DOM.
    *
-   * @example: `this.hasSlot("header")`
+   * @example this.hasSlot("header");
    */
   hasSlot(name) {
     if (!name) {
@@ -1016,4 +1027,5 @@ class PFElement extends HTMLElement {
 
 autoReveal(PFElement.log);
 
+/** @module PFElement */
 export default PFElement;

elements/pfelement/src/pfelement.js

@@ -1,5 +1,5 @@
 // @POLYFILL  Array.includes
-// https://tc39.github.io/ecma262/#sec-array.prototype.includes
+/** @see https://tc39.github.io/ecma262/#sec-array.prototype.includes */
 if (!Array.prototype.includes) {
   Object.defineProperty(Array.prototype, "includes", {
     value: function(valueToFind, fromIndex) {
@@ -51,7 +51,7 @@ if (!Array.prototype.includes) {
 }
 
 // @POLYFILL Object.entries
-// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries
+/** @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries */
 if (!Object.entries) {
   Object.entries = function(obj) {
     var ownProps = Object.keys(obj),
@@ -64,7 +64,7 @@ if (!Object.entries) {
 }
 
 // @POLYFILL String.startsWith
-// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith#polyfill
+/** @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith#polyfill */
 if (!String.prototype.startsWith) {
   Object.defineProperty(String.prototype, "startsWith", {
     value: function(search, rawPos) {

elements/pfelement/src/polyfills--pfelement.js

@@ -1,10 +1,21 @@
 let logger = () => null;
 
+/**
+ * Reveal web components when loading is complete by removing the unresolved attribute
+ * from the body tag; log the event.
+ * @throws debugging log indicating the reveal event
+ */
 export function reveal() {
   logger(`[reveal] elements ready, revealing the body`);
   window.document.body.removeAttribute("unresolved");
 }
 
+/**
+ * Auto-reveal functionality prevents a flash of unstyled content before components
+ * have finished loading.
+ * @param {function} logFunction
+ * @see https://github.com/github/webcomponentsjs#webcomponents-loaderjs
+ */
 export function autoReveal(logFunction) {
   logger = logFunction;
   // If Web Components are already ready, run the handler right away.  If they
@@ -22,6 +33,10 @@ export function autoReveal(logFunction) {
   }
 }
 
+/**
+ * Reveal web components when loading is complete and log event.
+ * @throws debugging log indicating the web components are ready
+ */
 function handleWebComponentsReady() {
   logger("[reveal] web components ready");
   reveal();

elements/pfelement/src/reveal.js

@@ -39,7 +39,7 @@ module.exports = function factory({
   const fs = require("fs");
   const path = require("path");
   const replace = require("gulp-replace");
-  const clean = require("gulp-clean");
+  const del = require("del");
   const gulpif = require("gulp-if");
   const gulpmatch = require("gulp-match");
 
@@ -64,14 +64,14 @@ module.exports = function factory({
   const decomment = require("decomment");
 
   // Delete the temp directory
-  task("clean", () => src([
-    paths.temp,
-    paths.compiled
-  ], {
-    cwd: paths.root,
-    read: false,
-    allowEmpty: true
-  }).pipe(clean()));
+  task("clean", () => del([
+      paths.temp,
+      paths.compiled
+    ], {
+      cwd: paths.root,
+      read: false,
+      allowEmpty: true
+    }));
 
   // Compile the sass into css, compress, autoprefix
   task("compile:styles", () => src("*.{scss,css}", {
@@ -294,14 +294,14 @@ ${fs
   task("bundle", () => shell.task("../../node_modules/.bin/rollup -c"));
 
   // Delete the temp directory
-  task("clean:post", () => src([
-    "*.min.css",
-    "*.umd.js"
-  ], {
-    cwd: paths.temp,
-    read: false,
-    allowEmpty: true
-  }).pipe(clean()));
+  task("clean:post", () => del([
+      "*.min.css",
+      "*.umd.js"
+    ], {
+      cwd: paths.temp,
+      read: false,
+      allowEmpty: true
+    }));
 
   task(
     "build",