Add support for ES5 classes and @classdesc with auto-generation of constructors

Author: ShukantPal

.idea/misc.xml

@@ -28,7 +28,17 @@
 					"type": "ClassDoc",
 					"scope": "static",
 					"brief": "",
-					"description": ""
+					"description": "",
+					"members": [
+						{
+							"name": "constructor",
+							"type": "MethodDoc",
+							"access": "public",
+							"scope": "instance",
+							"brief": "",
+							"description": ""
+						}
+					]
 				},
 				{
 					"name": "AbstractRenderer",
@@ -42,6 +52,14 @@
 							"scope": "instance",
 							"brief": "<p>The background color to fill if not transparent</p>",
 							"description": ""
+						},
+						{
+							"name": "constructor",
+							"type": "MethodDoc",
+							"access": "public",
+							"scope": "instance",
+							"brief": "",
+							"description": ""
 						}
 					]
 				},
@@ -475,13 +493,17 @@
 					"name": "Road",
 					"type": "ClassDoc",
 					"brief": "<p>This is another road class.</p>",
-					"description": ""
-				},
-				{
-					"name": "Road",
-					"type": "ClassDoc",
-					"brief": "<p>Road represents a drivable 2D path for vehicles.</p>",
-					"description": ""
+					"description": "",
+					"members": [
+						{
+							"name": "constructor",
+							"type": "MethodDoc",
+							"access": "public",
+							"scope": "instance",
+							"brief": "<p>This is another road class.</p>",
+							"description": ""
+						}
+					]
 				},
 				{
 					"name": "DEFAULT_LANES",
@@ -509,7 +531,17 @@
 					"name": "Transaction",
 					"type": "ClassDoc",
 					"brief": "",
-					"description": ""
+					"description": "",
+					"members": [
+						{
+							"name": "constructor",
+							"type": "MethodDoc",
+							"access": "public",
+							"scope": "instance",
+							"brief": "",
+							"description": ""
+						}
+					]
 				}
 			]
 		},
@@ -519,6 +551,14 @@
 			"brief": "<p>Bean class</p>",
 			"description": "",
 			"members": [
+				{
+					"name": "constructor",
+					"type": "MethodDoc",
+					"access": "public",
+					"scope": "instance",
+					"brief": "<p>Bean class</p>",
+					"description": ""
+				},
 				{
 					"name": "roast",
 					"type": "MethodDoc",
@@ -590,6 +630,14 @@
 					"brief": "<p>Register a retail dealer for buying a car from</p>",
 					"description": ""
 				},
+				{
+					"name": "constructor",
+					"type": "MethodDoc",
+					"access": "public",
+					"scope": "instance",
+					"brief": "<p><em>Simulation</em> for a automobile that can drive on a manifold surface.</p>",
+					"description": ""
+				},
 				{
 					"name": "onCrash",
 					"type": "MethodDoc",
@@ -635,12 +683,56 @@
 				}
 			]
 		},
+		{
+			"name": "ExampleFactory",
+			"type": "ClassDoc",
+			"description": "<p>{@link ExampleFactory} can be used to build examples.</p>\n<pre><code class=\"hljs language-js\"><span class=\"hljs-comment\">// <span class=\"hljs-doctag\">TODO:</span> Make the API interesting</span>\nExampleFactory.getInstance()\n .build()\n</code></pre>",
+			"members": [
+				{
+					"name": "getInstance",
+					"type": "MethodDoc",
+					"scope": "static",
+					"brief": "<p>Gets a lazily-initialized, shared singleton instance of {@link ExampleFactory}.</p>",
+					"description": ""
+				},
+				{
+					"name": "build",
+					"type": "MethodDoc",
+					"scope": "instance",
+					"brief": "<p>Build the road.</p>",
+					"description": ""
+				},
+				{
+					"name": "constructor",
+					"type": "MethodDoc",
+					"access": "public",
+					"scope": "instance",
+					"brief": "<p>This constructor should only be used for custom contexts.</p>",
+					"description": ""
+				},
+				{
+					"name": "getContext",
+					"type": "MethodDoc",
+					"scope": "instance",
+					"brief": "<p>Get the context of this factory.</p>",
+					"description": ""
+				}
+			]
+		},
 		{
 			"name": "Gravity",
 			"type": "ClassDoc",
 			"brief": "<p>This class shouldn't be documented!</p>",
 			"description": "",
 			"members": [
+				{
+					"name": "constructor",
+					"type": "MethodDoc",
+					"access": "public",
+					"scope": "instance",
+					"brief": "<p>This class shouldn't be documented!</p>",
+					"description": ""
+				},
 				{
 					"name": "force",
 					"type": "MethodDoc",

example/example.api.json

@@ -23,7 +23,7 @@
   },
   "scripts": {
     "unit-test": "",
-    "build": "webdoc --tutorials ./tutorials --site-root example-documentation --site-domain https://webdoc-labs.github.io",
+    "build": "webdoc --tutorials ./tutorials --site-domain https://webdoc-labs.github.io",
     "build-next": "cd .. && webdoc && cd example",
     "build-pixi-api": "cd ../../pixi-api && webdoc && cd ../webdoc/example",
     "build-pixi-api-prod": "cd ../../pixi-api && webdoc --site-root pixi-api && cd ../webdoc/example",

example/package.json

@@ -0,0 +1,69 @@
+/**
+ * A namespace dedicated to road manipulation utilites.
+ *
+ * @namespace
+ */
+const R = {
+  /**
+   * Builds a road
+   *
+   * @param {string} address
+   * @return {ExampleFactory}
+   */
+  buildRoad(address) {
+    return null;
+  },
+
+  /**
+   * The default no. of lanes per one side of road
+   */
+  DEFAULT_LANES: 4,
+};
+
+/**
+ * This constructor should only be used for custom contexts.
+ *
+ * @classdesc
+ * {@link ExampleFactory} can be used to build examples.
+ *
+ * ```js
+ * // TODO: Make the API interesting
+ * ExampleFactory.getInstance()
+ *  .build()
+ * ```
+ *
+ * @param {ExampleContext}[context=null] - A custom context for the factory.
+ * @class
+ */
+export function ExampleFactory(context= null) {
+
+}
+
+/**
+ * Get the context of this factory.
+ *
+ * @return {ExampleContext}
+ */
+ExampleFactory.prototype.getContext = function() {
+  return null;
+}
+
+/**
+ * Build the road.
+ */
+ExampleFactory.prototype.build = function() {
+
+}
+
+/**
+ * Gets a lazily-initialized, shared singleton instance of {@link ExampleFactory}.
+ *
+ * @returns {ExampleFactory}
+ */
+ExampleFactory.getInstance = function () {
+  if (!ExampleFactory.__instance) {
+    ExampleFactory.__instance = new ExampleFactory();
+  }
+
+  return ExampleFactory.__instance;
+}

example/src/ExampleFactory.js

@@ -9466,7 +9466,6 @@ function makeIds(data, collector) {
   };
 })(function Explorer(_ref2) {
   var isOpen = _ref2.isOpen,
-      setOpen = _ref2.setOpen,
       expandedItems = _ref2.expandedItems,
       setExpandedItems = _ref2.setExpandedItems,
       toggleItem = _ref2.toggleItem,
@@ -9485,9 +9484,6 @@ function makeIds(data, collector) {
   var _useExplorerStyles = useExplorerStyles(),
       root = _useExplorerStyles.root;
 
-  var toggleOpen = external_React_default.a.useCallback(function () {
-    return setOpen(!isOpen);
-  }, [isOpen]);
   var children = [];
   var explorerTree = window.appData.explorerTree;
 

example/src/Road.js

@@ -229,9 +229,13 @@ export default function extractSymbol(
         nodeSymbol.meta.type = "PropertyDoc";
       }
 
+      let isExpression = false;
+
       if (isExpressionStatement(node)) {
         // Literal property
 
+        isExpression = true;
+
         const object = resolveObject(node.expression.left);
         const scope = isInstancePropertyAssignment(node.expression.left) ?
           "instance" : "static";
@@ -251,7 +255,7 @@ export default function extractSymbol(
       }
 
       if (isFunctionExpression(init) || isArrowFunctionExpression(init)) {
-        nodeSymbol.meta.type = isObjectProperty(node) ? "MethodDoc" : "FunctionDoc";
+        nodeSymbol.meta.type = isObjectProperty(node) || isExpression ? "MethodDoc" : "FunctionDoc";
 
         nodeSymbol.meta.params = extractParams(init);
         nodeSymbol.meta.returns = extractReturns(init);

packages/webdoc-default-template/static/scripts/default-template.js

@@ -11,6 +11,7 @@ export {parseExtends, parseImplements, parseMixes} from "./parseExtendsImplement
 export {
   parseAbstract,
   parseAuthor,
+  parseClassDesc,
   parseCopyright,
   parseDefault,
   parseDeprecated,

packages/webdoc-parser/src/symbols-babel/extract-symbol.js

@@ -4,6 +4,7 @@ import type {
   AbstractTag,
   AuthorTag,
   BaseDoc,
+  ClassDescTag,
   CopyrightTag,
   DataType,
   DefaultTag,
@@ -58,6 +59,13 @@ export function parseAuthor(value: string, doc: $Shape<BaseDoc>): $Shape<AuthorT
   };
 }
 
+export function parseClassDesc(value: string, _doc: $Shape<BaseDoc>): $Shape<ClassDescTag> {
+  return {
+    value,
+    type: "ClassDescTag",
+  };
+}
+
 export function parseCopyright(value: string, doc: $Shape<BaseDoc>): $Shape<CopyrightTag> {
   doc.copyright = value;
 

packages/webdoc-parser/src/tag-parsers/index.js

@@ -2,6 +2,7 @@
 
 import type {Doc, RootDoc} from "@webdoc/types";
 import modDiscoverMembers from "./mod-discover-members";
+import modES5Constructor from './mod-es5-constructor';
 import modPackageApi from "./mod-package-api";
 import modPrune from "./mod-prune";// Next line is f'd up b/c the compiler ran on that file
 import modResolveMemberof from "./mod-resolve-memberof"; // eslint-disable-line
@@ -52,7 +53,7 @@ export const STAGE_AST_LIKE = 100;
 
 /**
  * The doctree-mod should run when symbols are placed in their documented parents. The
- * `@modResolveMemberof` tag is resolved in this stage. This occurs after {@code STAGE_AST_LIKE}.
+ * `@memberof` tag is resolved in this stage. This occurs after {@code STAGE_AST_LIKE}.
  *
  * Example:
  * ```js
@@ -125,6 +126,7 @@ export function registerDoctreeMod(
 }
 
 // These are the in-built doctree-mods.
+registerDoctreeMod("ASTMemberResolution", STAGE_AST_LIKE, modES5Constructor);
 registerDoctreeMod("ASTMemberResolution", STAGE_AST_LIKE, modResolveMembers);
 registerDoctreeMod("MemberOfResolution", STAGE_SYMBOLS_RESOLVED, modResolveMemberof);
 registerDoctreeMod("ExtendsImplementsMixesResolution", STAGE_SYMBOLS_RESOLVED, modResolveRelated);