api-extractor: fix namespace "name" field; api-documenter: fix api reference for namespace content, and render namespace item

adventure-yunfei · adventure-yunfei · commit 568db17d680c · 2018-08-16T14:41:43.000+08:00
diff --git a/apps/api-documenter/src/markdown/MarkdownDocumenter.ts b/apps/api-documenter/src/markdown/MarkdownDocumenter.ts
@@ -76,6 +76,11 @@ export class MarkdownDocumenter {
 
     markupPage.elements.push(...apiPackage.summary);
 
+    const namespacesTable: IMarkupTable = Markup.createTable([
+      Markup.createTextElements('Namespaces'),
+      Markup.createTextElements('Description'),
+    ]);
+
     const classesTable: IMarkupTable = Markup.createTable([
       Markup.createTextElements('Class'),
       Markup.createTextElements('Description')
@@ -152,6 +157,15 @@ export class MarkdownDocumenter {
           );
           this._writeEnumPage(docChild);
           break;
+        case 'namespace':
+          namespacesTable.rows.push(
+            Markup.createTableRow([
+              docItemTitle,
+              docChildDescription
+            ])
+          );
+          this._writePackagePage(docChild);
+          break;
       }
     }
 
@@ -160,6 +174,11 @@ export class MarkdownDocumenter {
       markupPage.elements.push(...apiPackage.remarks);
     }
 
+    if (namespacesTable.rows.length > 0) {
+      markupPage.elements.push(Markup.createHeading1('Namespaces'));
+      markupPage.elements.push(namespacesTable);
+    }
+
     if (classesTable.rows.length > 0) {
       markupPage.elements.push(Markup.createHeading1('Classes'));
       markupPage.elements.push(classesTable);
diff --git a/apps/api-documenter/src/utils/DocItemSet.ts b/apps/api-documenter/src/utils/DocItemSet.ts
@@ -122,11 +122,13 @@ export class DocItem {
   }
 
   public getApiReference(): IApiItemReference {
-    const reference: IApiItemReference = {
+    const reference: IApiItemReference & { moreHierarchies: string[]; } = {
       scopeName: '',
       packageName: '',
       exportName: '',
-      memberName: ''
+      memberName: '',
+      // TODO: quick fix for api ref inside namespace, need to adjust IApiItemReference later
+      moreHierarchies: []
     };
     let i: number = 0;
     for (const docItem of this.getHierarchy()) {
@@ -142,7 +144,9 @@ export class DocItem {
           reference.memberName = docItem.name;
           break;
         default:
-          throw new Error('Unable to create API reference for ' + this.name);
+          reference.moreHierarchies.push(docItem.name);
+          break;
+          // throw new Error('Unable to create API reference for ' + this.name);
       }
       ++i;
     }
@@ -209,7 +213,9 @@ export class DocItemSet {
    * Attempts to find the DocItem described by an IApiItemReference.  If no matching item is
    * found, then undefined is returned.
    */
-  public resolveApiItemReference(reference: IApiItemReference): IDocItemSetResolveResult {
+  public resolveApiItemReference(
+    reference: IApiItemReference & { moreHierarchies?: string[]; }
+  ): IDocItemSetResolveResult {
     const result: IDocItemSetResolveResult = {
       docItem: undefined,
       closestMatch: undefined
@@ -219,7 +225,11 @@ export class DocItemSet {
 
     let current: DocItem | undefined = undefined;
 
-    for (const nameToMatch of [packageName, reference.exportName, reference.memberName]) {
+    for (const nameToMatch of [
+      packageName, reference.exportName, reference.memberName,
+      // TODO: quick fix for api ref inside namespace, need to adjust IApiItemReference later
+      ...(reference.moreHierarchies || [])
+    ]) {
       if (!nameToMatch) {
         // Success, since we ran out of stuff to match
         break;
diff --git a/apps/api-extractor/src/ast/AstNamespace.ts b/apps/api-extractor/src/ast/AstNamespace.ts
@@ -31,7 +31,12 @@ export class AstNamespace extends AstModule {
   constructor(options: IAstItemOptions) {
     super(options);
     this.kind = AstItemKind.Namespace;
-    this.name = options.declarationSymbol.name;
+
+    /* comment following line to use default "this.exportSymbol.name"
+        fix case for code: import { sub } from './sub'; export { sub };
+        previously "name" will be like "<filepath>/<to>/<sub>" instead of just "sub"
+    */
+    // this.name = options.declarationSymbol.name;
 
     const exportSymbols: ts.Symbol[] = this.typeChecker.getExportsOfModule(this.declarationSymbol);
     if (exportSymbols) {
