feat(analyzer): ignore and internal jsdoc

fixes #21

packages/analyzer/fixtures/class-jsdoc/output.json

@@ -94,8 +94,8 @@
           "superclass": {
             "name": "HTMLElement"
           },
-          "tagName": "my-element",
           "summary": "This is MyElement",
+          "tagName": "my-element",
           "customElement": true
         }
       ],

packages/analyzer/fixtures/jsdoc-ignore-internal/fixture/custom-elements.json

@@ -0,0 +1,66 @@
+{
+  "schemaVersion": "1.0.0",
+  "readme": "",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "fixtures/jsdoc-ignore-internal/package/my-element.js",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "variable",
+          "type": {
+            "text": "string"
+          },
+          "default": "'var'"
+        },
+        {
+          "kind": "class",
+          "description": "",
+          "name": "IncludeMe",
+          "members": [
+            {
+              "kind": "field",
+              "name": "included",
+              "type": {
+                "text": "string"
+              },
+              "default": "'hello world'"
+            }
+          ],
+          "superclass": {
+            "name": "HTMLElement"
+          },
+          "tagName": "include-me",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "variable",
+          "declaration": {
+            "name": "variable",
+            "module": "fixtures/jsdoc-ignore-internal/package/my-element.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "IncludeMe",
+          "declaration": {
+            "name": "IncludeMe",
+            "module": "fixtures/jsdoc-ignore-internal/package/my-element.js"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "include-me",
+          "declaration": {
+            "name": "IncludeMe",
+            "module": "fixtures/jsdoc-ignore-internal/package/my-element.js"
+          }
+        }
+      ]
+    }
+  ]
+}

packages/analyzer/fixtures/jsdoc-ignore-internal/output.json

@@ -0,0 +1,66 @@
+{
+  "schemaVersion": "1.0.0",
+  "readme": "",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "fixtures/jsdoc-ignore-internal/package/my-element.js",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "variable",
+          "type": {
+            "text": "string"
+          },
+          "default": "'var'"
+        },
+        {
+          "kind": "class",
+          "description": "",
+          "name": "IncludeMe",
+          "members": [
+            {
+              "kind": "field",
+              "name": "included",
+              "type": {
+                "text": "string"
+              },
+              "default": "'hello world'"
+            }
+          ],
+          "superclass": {
+            "name": "HTMLElement"
+          },
+          "tagName": "include-me",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "variable",
+          "declaration": {
+            "name": "variable",
+            "module": "fixtures/jsdoc-ignore-internal/package/my-element.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "IncludeMe",
+          "declaration": {
+            "name": "IncludeMe",
+            "module": "fixtures/jsdoc-ignore-internal/package/my-element.js"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "include-me",
+          "declaration": {
+            "name": "IncludeMe",
+            "module": "fixtures/jsdoc-ignore-internal/package/my-element.js"
+          }
+        }
+      ]
+    }
+  ]
+}

packages/analyzer/fixtures/jsdoc-ignore-internal/package/my-element.js

@@ -0,0 +1,38 @@
+/** @internal */
+export const dontIncludeMe = false; // should not be in declarations
+
+/** @ignore */
+export const meNeither = false; // should not be in declarations
+
+export const variable = 'var';
+
+/** @ignore */
+export class IgnoreMe extends HTMLElement { }
+
+customElements.define("ignore-me", IgnoreMe);
+
+export class IncludeMe extends HTMLElement {
+  included = 'hello world';
+
+  /** @ignore */
+  sneaky = 'deaky';
+
+  /** @internal */
+  hideMe() {
+    return '🙈'
+  }
+}
+
+customElements.define("include-me", IncludeMe);
+
+/** @ignore */
+var ignoreMePlease = 'haha';
+
+/** @internal */
+var excludeMe, andMe = 'something private';
+
+export {
+  ignoreMePlease,
+  excludeMe,
+  andMe,
+}

packages/analyzer/src/features/analyse-phase/arrow-function.js

@@ -5,7 +5,7 @@ import { createArrowFunction } from './creators/createArrowFunction.js';
 
 /**
  * arrowFunctionPlugin
- * 
+ *
  * handles arrow functions
  */
 export function arrowFunctionPlugin() {
@@ -16,11 +16,11 @@ export function arrowFunctionPlugin() {
         case ts.SyntaxKind.VariableStatement:
           if(!isMixin(node) && hasInitializer(node)) {
             const functionLike = createArrowFunction(node);
-            moduleDoc.declarations.push(functionLike);
+            if (functionLike)
+              moduleDoc.declarations.push(functionLike);
           }
           break;
       }
     }
   }
 }
-

packages/analyzer/src/features/analyse-phase/class-jsdoc.js

@@ -4,7 +4,7 @@ import { safe } from '../../utils/index.js';
 
 /**
  * CLASS-JSDOC
- * 
+ *
  * Deals with any JSDoc above a class
  */
 export function classJsDocPlugin() {
@@ -18,10 +18,10 @@ export function classJsDocPlugin() {
 
           /**
            * Because we use a bunch of 'non-standard' JSDoc annotations, TS doesn't recognize most of them.
-           * Instead we use `comment-parser` to parse the JSDoc. 
-           * 
+           * Instead we use `comment-parser` to parse the JSDoc.
+           *
            * Loops through each JSDoc (yes, there can be multiple) above a class, and parses every JSDoc annotation
-           * 
+           *
            * Checks to see if the item is already in the classDoc, and if so merge and overwrite (JSDoc takes precedence)
            */
           node?.jsDoc?.forEach(jsDoc => {
@@ -41,7 +41,7 @@ export function classJsDocPlugin() {
                     const attributeAlreadyExists = classDoc?.attributes?.find(attr => attr.name === jsDoc.name);
                     let attributeDoc = attributeAlreadyExists || {};
                     attributeDoc = handleClassJsDoc(attributeDoc, jsDoc);
-                    if(!attributeAlreadyExists) {
+                    if(attributeDoc && !attributeAlreadyExists) {
                       classDoc.attributes.push(attributeDoc);
                     }
                     break;
@@ -51,7 +51,7 @@ export function classJsDocPlugin() {
                     let fieldDoc = fieldAlreadyExists || {};
                     fieldDoc = handleClassJsDoc(fieldDoc, jsDoc);
                     fieldDoc.kind = 'field';
-                    if(!fieldAlreadyExists) {
+                    if(fieldDoc && !fieldAlreadyExists) {
                       classDoc.members.push(fieldDoc);
                     }
                     break;
@@ -60,25 +60,28 @@ export function classJsDocPlugin() {
                     const eventAlreadyExists = classDoc?.events?.find(event => event.name === jsDoc.name);
                     let eventDoc = eventAlreadyExists || {};
                     eventDoc = handleClassJsDoc(eventDoc, jsDoc);
-                    if(!eventAlreadyExists) {
+                    if(eventDoc && !eventAlreadyExists) {
                       classDoc.events.push(eventDoc);
                     }
                     break;
                   case 'csspart':
                     let cssPartDoc = {};
                     cssPartDoc = handleClassJsDoc(cssPartDoc, jsDoc);
-                    classDoc.cssParts.push(cssPartDoc);
+                    if (cssPartDoc)
+                      classDoc.cssParts.push(cssPartDoc);
                     break;
                   case 'cssprop':
                   case 'cssproperty':
                     let cssPropertyDoc = {};
                     cssPropertyDoc = handleClassJsDoc(cssPropertyDoc, jsDoc);
-                    classDoc.cssProperties.push(cssPropertyDoc);
+                    if (cssPropertyDoc)
+                      classDoc.cssProperties.push(cssPropertyDoc);
                     break;
                   case 'slot':
                     let slotDoc = {};
                     slotDoc = handleClassJsDoc(slotDoc, jsDoc);
-                    classDoc.slots.push(slotDoc);
+                    if (slotDoc)
+                      classDoc.slots.push(slotDoc);
                     break;
                   case 'tag':
                   case 'tagname':
@@ -99,8 +102,8 @@ export function classJsDocPlugin() {
             /**
              * Comment-parse doesn't handle annotations with only a description correctly, for example:
              * @summary foo bar
-             * will output only 'bar' as the description. 
-             * 
+             * will output only 'bar' as the description.
+             *
              * Instead, we use TS for this JSDoc annotation.
              */
             jsDoc?.tags?.forEach(tag => {

packages/analyzer/src/features/analyse-phase/classes.js

@@ -2,7 +2,7 @@ import { createClass } from './creators/createClass.js';
 
 /**
  * classPlugin
- * 
+ *
  * handles classes
  */
 export function classPlugin() {
@@ -12,9 +12,10 @@ export function classPlugin() {
       switch(node.kind) {
         case ts.SyntaxKind.ClassDeclaration:
           const klass = createClass(node, moduleDoc, context);
-          moduleDoc.declarations.push(klass);
+          if (klass)
+            moduleDoc.declarations.push(klass);
           break;
       }
     }
   }
-}
+}