DocumentedInterface -> Manifest (better name!)

Author: ShukantPal

packages/webdoc-cli/src/index.js

@@ -119,12 +119,12 @@ async function main(argv: yargs.Argv) {
 
   log.info(tag.Parser, "Parsing stage finished!");
 
-  const documentedInterface = external.fromTree(documentTree);
+  const manifest = external.fromTree(documentTree);
   const db = exportTaffy(documentTree);
 
-  documentedInterface.metadata.linker = "(unsigned)";
-  documentedInterface.metadata.siteDomain = config.template.siteDomain;
-  documentedInterface.metadata.siteRoot = config.template.siteRoot;
+  manifest.metadata.linker = "(unsigned)";
+  manifest.metadata.siteDomain = config.template.siteDomain;
+  manifest.metadata.siteRoot = config.template.siteRoot;
 
   const _path = `${getTemplate(config)}/publish`;
   // $FlowFixMe[unsupported-syntax]
@@ -136,7 +136,7 @@ async function main(argv: yargs.Argv) {
     config,
     doctree: documentTree,
     documentTree,
-    documentedInterface,
+    manifest,
     docDatabase: db,
     opts: config.opts,
     tutorials,
@@ -154,7 +154,7 @@ async function main(argv: yargs.Argv) {
   }
 
   if (config.opts && config.opts.export) {
-    fs.writeFileSync(config.opts.export, external.write(documentedInterface, argv.verbose));
+    fs.writeFileSync(config.opts.export, external.write(manifest, argv.verbose));
   }
 
   console.log(`@webdoc took ${Math.ceil(performance.now() - start)}ms to run!`);

packages/webdoc-default-template/helper/crawl/crawl.js

@@ -14,7 +14,7 @@ import type {
   RootDoc,
   DocType,
 } from "@webdoc/types";
-import type {DocumentedInterface} from "@webdoc/externalize";
+import type {Manifest} from "@webdoc/externalize";
 import type {ExplorerTarget} from './crawl-reference-explorer';
 
 export type CategorizedDocumentList = {
@@ -31,12 +31,12 @@ declare function crawl(tree: RootDoc, index: string): CrawlData;
 */
 
 function crawl(
-  documentedInterface /*: DocumentedInterface */,
+  manifest /*: Manifest */,
   index /*: string */,
 )/*: CrawlData */ {
-  const tree = documentedInterface.root;
+  const tree = manifest.root;
 
-  buildLinks(documentedInterface);
+  buildLinks(manifest);
 
   const crawlData /*: CrawlData */ = {
     index: buildIndex(tree),
@@ -67,10 +67,10 @@ function crawl(
 
 module.exports = ({crawl}/*: {crawl: typeof crawl} */);
 
-function buildLinks(documentedInterface /*: DocumentedInterface */) /*: void */ {
-  const registry = documentedInterface.registry;
+function buildLinks(manifest /*: Manifest */) /*: void */ {
+  const registry = manifest.registry;
 
-  model.traverse(documentedInterface.root, (doc) => {
+  model.traverse(manifest.root, (doc) => {
     if (doc.type === "RootDoc") {
       doc.packages.forEach((packageDoc) => {
         if (!registry[packageDoc.id]) {

packages/webdoc-default-template/helper/linker.js

@@ -8,7 +8,7 @@ exports.prepareLinker = async function(config) {
 
   if (Array.isArray(config.opts.import)) {
     for (const importUri of config.opts.import) {
-      await linker.loadDocumentedInterface(importUri);
+      await linker.loadManifest(importUri);
     }
   }
 };

packages/webdoc-default-template/publish.js

@@ -72,7 +72,7 @@ exports.publish = async function publish(options /*: PublishOptions */) {
 
   fse.ensureDir(outDir);
 
-  const crawlData = crawl(options.documentedInterface, index);
+  const crawlData = crawl(options.manifest, index);
   const appBarItems = _.merge(config.template.appBar.items, {
     /* NOTE: config.template.appBar.items is the primary object so we retain the order as the user
         desires. */

packages/webdoc-externalize/index.js.flow

@@ -1,7 +1,7 @@
 declare module "@webdoc/externalize" {
   import type {RootDoc} from "@webdoc/types";
 
-  declare export type DocumentedInterface = {
+  declare export type Manifest = {
     version: string;
     metadata: {
       linker?: "require('@webdoc/template-library').LinkerPlugin" | string;
@@ -15,9 +15,9 @@ declare module "@webdoc/externalize" {
     };
   };
 
-  declare export function fromTree(tree: RootDoc): DocumentedInterface;
-  declare export function read(data: string): DocumentedInterface;
-  declare export function write(doc: DocumentedInterface): string;
+  declare export function fromTree(tree: RootDoc): Manifest;
+  declare export function read(data: string): Manifest;
+  declare export function write(doc: Manifest): string;
 
   declare export default {
     fromTree,

packages/webdoc-externalize/src/read.js

@@ -3,7 +3,7 @@
 import * as model from "@webdoc/model";
 import {BASE_PROPS} from "./const";
 import type {Doc} from "@webdoc/types";
-import type {DocumentedInterface} from "./types";
+import type {Manifest} from "./types";
 import _ from "lodash";
 
 function deserializeTree(serialized: any, parent: ?Doc): Doc {
@@ -45,22 +45,22 @@ function deserializeTree(serialized: any, parent: ?Doc): Doc {
  * @param {string} data
  * @return {RootDoc}
  */
-export default function read(data: string): DocumentedInterface {
-  const documentedInterface = (JSON.parse(data): any);
+export default function read(data: string): Manifest {
+  const manifest = (JSON.parse(data): any);
 
-  if (!("version" in documentedInterface)) {
+  if (!("version" in manifest)) {
     return ({
       version: "0.0.0",
       metadata: {},
-      root: (deserializeTree(documentedInterface.root, null): any),
+      root: (deserializeTree(manifest.root, null): any),
       registry: {},
-    }: DocumentedInterface);
+    }: Manifest);
   }
 
   return {
-    version: documentedInterface.version,
-    metadata: documentedInterface.metadata,
-    root: (deserializeTree(documentedInterface.root, null): any),
-    registry: documentedInterface.registry,
+    version: manifest.version,
+    metadata: manifest.metadata,
+    root: (deserializeTree(manifest.root, null): any),
+    registry: manifest.registry,
   };
 }

packages/webdoc-externalize/src/types.js

@@ -24,7 +24,7 @@ export type SerializedReturn = {
   dataType: SerializedDataType,
 };
 
-export type DocumentedInterface = {
+export type Manifest = {
   version: string;
   metadata: {
     siteRoot?: string;

packages/webdoc-externalize/src/write.js

@@ -14,7 +14,7 @@ import type {
   RootDoc,
 } from "@webdoc/types";
 import type {
-  DocumentedInterface,
+  Manifest,
   SerializedDataType,
   SerializedParam,
   SerializedReturn,
@@ -121,34 +121,34 @@ function serializeTree(doc: Doc): any {
  * Create an documented interface the document tree, with no metadata.
  *
  * @param {RootDoc} documentTree
- * @return {DocumentedInterface}
+ * @return {Manifest}
  */
-export function fromTree(documentTree: RootDoc): DocumentedInterface {
-  const documentedInterface = {
+export function fromTree(documentTree: RootDoc): Manifest {
+  const manifest = {
     version: LATEST_VERSION,
     metadata: {},
     root: documentTree,
     registry: {},
   };
 
-  return documentedInterface;
+  return manifest;
 }
 
 /**
  * Serialize the documented interface into a JSON string.
  *
- * @param {DocumentedInterface} documentedInterface
+ * @param {Manifest} manifest
  * @param {boolean}[indent=false] - Whether to indent
  * @return {string} - Serialized JSON string
  * @see serializeTree
  */
-export default function write(documentedInterface: DocumentedInterface, indent?: boolean): string {
+export default function write(manifest: Manifest, indent?: boolean): string {
   return JSON.stringify(
     {
-      version: documentedInterface.version,
-      metadata: documentedInterface.metadata,
-      root: serializeTree(documentedInterface.root),
-      registry: documentedInterface.registry,
+      version: manifest.version,
+      metadata: manifest.metadata,
+      root: serializeTree(manifest.root),
+      registry: manifest.registry,
     },
     null,
     indent ? "\t" : "",

packages/webdoc-externalize/test/read-write.js

@@ -33,8 +33,8 @@ describe("@webdoc/externalize (read-write test)", function() {
        */
     `);
 
-    const documentedInterface = external.fromTree(inputTree);
-    const {root: outputTree} = external.read(external.write(documentedInterface));
+    const manifest = external.fromTree(inputTree);
+    const {root: outputTree} = external.read(external.write(manifest));
 
     expect(outputTree.members.length).to.equal(2);
 

packages/webdoc-template-library/src/template-plugins/LinkerPlugin.js

@@ -130,9 +130,9 @@ function LinkerPluginShell() {
 
     /**
      * Loaded documented interfaces that can be used to resolve links to external APIs.
-     * @type {DocumentedInterface[]}
+     * @type {Manifest[]}
      */
-    loadedInterfaces = [];
+    importedManifests = [];
 
     /**
      * Load the documented interface into this linker so you can resolve links to those documents.
@@ -141,7 +141,7 @@ function LinkerPluginShell() {
      *   or a file ./apis/lib.json)
      * @return {Promise<void>}
      */
-    async loadDocumentedInterface(uri: string) {
+    async loadManifest(uri: string) {
       let isURL = true;
 
       try {
@@ -158,9 +158,9 @@ function LinkerPluginShell() {
         contents = await fs.readFile(path.join(process.cwd(), uri), "utf8");
       }
 
-      const documentedInterface = external.read(contents);
-      const {registry} = documentedInterface;
-      const {siteDomain, siteRoot} = documentedInterface.metadata;
+      const manifest = external.read(contents);
+      const {registry} = manifest;
+      const {siteDomain, siteRoot} = manifest.metadata;
 
       if (!siteDomain) {
         throw new Error("Imported documented interfaces must have a siteDomain!");
@@ -175,7 +175,7 @@ function LinkerPluginShell() {
         }
       }
 
-      this.loadedInterfaces.push(documentedInterface);
+      this.importedManifests.push(manifest);
     }
 
     /**
@@ -320,8 +320,8 @@ function LinkerPluginShell() {
             this.queryCache.set(docPath, fileUrl);
           }
         } else {
-          for (let i = 0; i < this.loadedInterfaces.length && !fileUrl; i++) {
-            const externalInterface = this.loadedInterfaces[i];
+          for (let i = 0; i < this.importedManifests.length && !fileUrl; i++) {
+            const externalInterface = this.importedManifests[i];
             const doc = query(docPath, externalInterface.root)[0];
 
             if (doc) {