Merge pull request #69 from webdoc-labs/feature/readonly

Feature: First-class readonly support

Author: ShukantPal

packages/webdoc-parser/src/symbols-babel/build-symbol-tree.js

@@ -186,7 +186,7 @@ export default function buildSymbolTree(
       let idoc;
 
       try {
-        idoc = captureSymbols(nodePath.node, scope);
+        idoc = captureSymbols(nodePath, scope);
       } catch (e) {
         console.error(ancestorStack);
         console.log(node);
@@ -255,10 +255,11 @@ export default function buildSymbolTree(
 // them as a child of parent.
 //
 // The returned symbol is the one backed by the AST node.
-function captureSymbols(node: Node, parent: Symbol): ?Symbol {
+function captureSymbols(nodePath: NodePath, parent: Symbol): ?Symbol {
+  const node = nodePath.node;
   const symbolInfo = {};
 
-  extractSymbol(node, parent, symbolInfo);
+  extractSymbol(nodePath, parent, symbolInfo);
 
   let {
     name: simpleName,

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

@@ -8,6 +8,7 @@ import {
   type FunctionExpression,
   type MemberExpression,
   type Node,
+  type NodePath,
   type VariableDeclarator,
   isArrowFunctionExpression,
   isAssignmentExpression,
@@ -54,7 +55,7 @@ import {
 // + Set the appopriate flags
 // + Set isInit & initComment if the symbol has a initializer child
 export default function extractSymbol(
-  node: Node,
+  nodePath: NodePath,
   parent: Symbol,
   out: {
     name?: ?string,
@@ -65,6 +66,8 @@ export default function extractSymbol(
     init?: ?Node
   },
 ): void {
+  const node = nodePath.node;
+
   let name;
   let flags = out.flags || 0;
   let isInit = false;
@@ -101,6 +104,7 @@ export default function extractSymbol(
     name = node.key.name;
 
     nodeSymbol.meta.access = node.access || node.accessibility;
+    nodeSymbol.meta.readonly = node.readonly;
     nodeSymbol.meta.dataType = extractType(node);
     nodeSymbol.meta.scope = node.static ? "static" : "instance";
     nodeSymbol.meta.type = "PropertyDoc";
@@ -173,6 +177,11 @@ export default function extractSymbol(
     } else if (isVariableDeclarator(node)) {
       name = node.id.name;
       init = resolveInit(node);
+
+      // Variables defined with the const keyword are inferred to be readonly.
+      if (nodePath.parent && nodePath.parent.kind === "const") {
+        nodeSymbol.meta.readonly = true;
+      }
     } else {// ObjectProperty
       name = node.key.name;
       init = node.value;

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

@@ -20,6 +20,7 @@ export {
   parseTodo,
   parseThrows,
   parseType,
+  parseReadonly,
   parseSee,
   parseSince,
 } from "./parseSimple";

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

@@ -11,6 +11,7 @@ import type {
   ExampleTag,
   LicenseTag,
   NameTag,
+  ReadonlyTag,
   SeeTag,
   SinceTag,
   ThrowsTag,
@@ -33,6 +34,8 @@ import {parseTypedDescription} from "./helper";
 // @todo <TODO>
 // @throws <ERROR_TYPE>
 // @type {TYPE}
+// @readonly
+// @readOnly
 // @see <URL | DOC_PATH>
 // @since <WHEN>
 
@@ -153,6 +156,15 @@ export function parseType(value: string, doc: $Shape<{ dataType?: ?DataType }>):
   };
 }
 
+export function parseReadonly(value: string, doc: $Shape<BaseDoc>): $Shape<ReadonlyTag> {
+  doc.readonly = true;
+
+  return {
+    value,
+    type: "ReadonlyTag",
+  };
+}
+
 export function parseSee(value: string, doc: $Shape<BaseDoc>): $Shape<SeeTag> {
   if (!doc.see) {
     doc.see = [];

packages/webdoc-parser/src/transformer/symbol-to-doc.js

@@ -32,6 +32,7 @@ import {
   parseProperty,
   parseProtected,
   parsePublic,
+  parseReadonly,
   parseReturn,
   parseScope,
   parseSee,
@@ -92,6 +93,8 @@ const TAG_PARSERS: { [id: string]: TagParser } = {
   "protected": parseProtected,
   "private": parsePrivate,
   "public": parsePublic,
+  "readOnly": parseReadonly,
+  "readonly": parseReadonly,
   "return": parseReturn,
   "returns": parseReturn, // alias @return
   "scope": parseScope,
@@ -135,6 +138,7 @@ export default function symbolToDoc(symbol: Symbol): ?Doc {
   options.access = symbol.meta.access;
   options.dataType = symbol.meta.dataType;
   options.defaultValue = symbol.meta.defaultValue;
+  options.readonly = symbol.meta.readonly;
   options.scope = symbol.meta.scope;
   options.loc = symbol.loc;
 

packages/webdoc-parser/src/types/Symbol.js

@@ -30,6 +30,7 @@ export type SymbolSignature = {
   implements?: ?Array<string | Symbol>,
   object?: ?string,
   params?: ?Array<$Shape<Param>>,
+  readonly?: boolean,
   returns?: ?Array<$Shape<Return>>,
   scope?: ?string,
   value?: ?string,

packages/webdoc-parser/test/lang-js.js

@@ -101,4 +101,15 @@ describe("@webdoc/parser.LanguageIntegration{@lang js}", function() {
     expect(symbolClassName.members[0].simpleName).to.equal("constructor");
     expect(symbolClassName.members[0].members.length).to.equal(0);
   });
+
+  it("should mark const variable declarations as readonly", function() {
+    const symtree = buildSymbolTree(`
+      const variable = "value";
+      let mutable = "mutable";
+    `);
+
+    expect(symtree.members.length).to.equal(2);
+    expect(symtree.members[0].meta.readonly).to.equal(true);
+    expect(symtree.members[1].meta.readonly).to.not.equal(true);
+  });
 });

packages/webdoc-parser/test/lang-ts.js

@@ -8,12 +8,11 @@ describe("@webdoc/parser.LanguageIntegration{@lang ts}", function() {
   it("should parse classes correctly", function() {
     let symtree = buildSymbolTree(`
       class ClassName {
-        private initProperty: number = 11;
+        private readonly initProperty: number = 11;
 
         constructor() {
           /**
            * This is a property whose data-type & access should be inferred.
-           * @default 9
            */
           this.initProperty = 9;
         }
@@ -50,6 +49,7 @@ describe("@webdoc/parser.LanguageIntegration{@lang ts}", function() {
     expect(symbolInitProperty.meta.access).to.equal("private");
     expect(symbolInitProperty.meta.defaultValue).to.equal(11);
     expect(symbolInitProperty.comment).to.not.equal("");
+    expect(symbolInitProperty.meta.readonly).to.equal(true);
   });
 
   it("should be able to parse type-casted objects for property symbols", function() {

packages/webdoc-parser/test/parse-ts.js

@@ -12,7 +12,7 @@ class Example {
   /**
    * Field description
    */
-  protected field: boolean = true;
+  protected readonly field: boolean = true;
 }
 `,
       path: ".ts",
@@ -27,6 +27,7 @@ class Example {
     expect(fieldDoc.access).to.equal("protected");
     expect(fieldDoc.dataType && fieldDoc.dataType[0]).to.equal("boolean");
     expect(fieldDoc.defaultValue).to.equal(true);
+    expect(fieldDoc.readonly).to.equal(true);
 
     // TODO: Fix this. No space should be there (added/not-fixed b/c this was
     // in a PR for different issue)

packages/webdoc-types/index.js.flow

@@ -70,6 +70,7 @@ export type BaseDoc = {
   fires?: [],
   license?: string,
   loc?: SymbolLocation,
+  readonly?: boolean,
   scope?: "static" | "instance" | "inner" | "default",
   see?: DocLink[],
   since?: string,
@@ -258,6 +259,7 @@ export type TagType =
   "NSTag" |
   "LicenseTag" |
   "ParamTag" |
+  "ReadonlyTag" |
   "ReturnTag" |
   "SeeTag" |
   "SinceTag" |
@@ -286,6 +288,7 @@ export type Tag =
   NSTag |
   LicenseTag |
   ParamTag |
+  ReadonlyTag |
   ReturnTag |
   SeeTag |
   SinceTag |
@@ -314,6 +317,7 @@ export type TagShape =
   $Shape<NSTag> |
   $Shape<LicenseTag> |
   $Shape<ParamTag> |
+  $Shape<ReadonlyTag> |
   $Shape<ReturnTag> |
   $Shape<SeeTag> |
   $Shape<SinceTag> |
@@ -455,6 +459,11 @@ export type ParamTag = {
   type: "ParamTag"
 };
 
+export type ReadonlyTag = {
+  ...BaseTag,
+  type: "ReadonlyTag"
+};
+
 export type ReturnTag = {
   ...TypedTag,
   type: "ReturnTag"