Implement naive autolinking for simple type references only

pgonzal · pgonzal · commit 9a093e339756 · 2018-06-25T15:46:51.000-07:00
diff --git a/apps/api-documenter/src/yaml/YamlDocumenter.ts b/apps/api-documenter/src/yaml/YamlDocumenter.ts
@@ -40,10 +40,48 @@ const yamlApiSchema: JsonSchema = JsonSchema.fromFile(path.join(__dirname, 'type
  */
 export class YamlDocumenter {
   private _docItemSet: DocItemSet;
+
+  // This is used by the _linkToUidIfPossible() workaround.
+  // It stores a mapping from type name (e.g. "MyClass") to the corresponding DocItem.
+  // If the mapping would be ambiguous (e.g. "MyClass" is defined by multiple packages)
+  // then it is excluded from the mapping.  Also excluded are DocItems (such as package
+  // and function) which are not typically used as a data type.
+  private _docItemsByTypeName: Map<string, DocItem>;
+
   private _outputFolder: string;
 
   public constructor(docItemSet: DocItemSet) {
     this._docItemSet = docItemSet;
+    this._docItemsByTypeName = new Map<string, DocItem>();
+
+    // Collect the _docItemsByTypeName table
+    const ambiguousNames: Set<string> = new Set<string>();
+
+    this._docItemSet.forEach((docItem: DocItem) => {
+      switch (docItem.kind) {
+        case DocItemKind.Class:
+        case DocItemKind.Enum:
+        case DocItemKind.Interface:
+          const typeName: string = docItem.name;
+          if (ambiguousNames.has(typeName)) {
+            break;
+          }
+
+          if (this._docItemsByTypeName.has(typeName)) {
+            // We saw this name before, so it's an ambiguous match
+            ambiguousNames.add(typeName);
+            break;
+          }
+
+          this._docItemsByTypeName.set(typeName, docItem);
+          break;
+      }
+    });
+
+    // Remove the ambiguous matches
+    for (const ambiguousName of ambiguousNames) {
+      this._docItemsByTypeName.delete(ambiguousName);
+    }
   }
 
   public generateFiles(outputFolder: string): void { // virtual
@@ -330,7 +368,7 @@ export class YamlDocumenter {
         .replace(/^\s*-\s+/, ''); // temporary workaround for people who mistakenly add a hyphen, e.g. "@returns - blah"
 
       syntax.return = {
-        type: [ apiMethod.returnValue.type ],
+        type: [ this._linkToUidIfPossible(apiMethod.returnValue.type) ],
         description: returnDescription
       };
     }
@@ -342,7 +380,7 @@ export class YamlDocumenter {
         {
            id: parameterName,
            description:  this._renderMarkdown(apiParameter.description, docItem),
-           type: [ apiParameter.type || '' ]
+           type: [ this._linkToUidIfPossible(apiParameter.type || '') ]
         } as IYamlParameter
       );
     }
@@ -364,7 +402,7 @@ export class YamlDocumenter {
 
     if (apiProperty.type) {
       syntax.return = {
-        type: [ apiProperty.type ]
+        type: [ this._linkToUidIfPossible(apiProperty.type) ]
       };
     }
   }
@@ -450,6 +488,25 @@ export class YamlDocumenter {
     return result;
   }
 
+  /**
+   * This is a temporary workaround to enable limited autolinking of API item types
+   * until the YAML file format is enhanced to support general hyperlinks.
+   * @remarks
+   * In the current version, fields such as IApiProperty.type allow either:
+   * (1) a UID identifier such as "node-core-library.JsonFile" which will be rendered
+   * as a hyperlink to that type name, or (2) a block of freeform text that must not
+   * contain any Markdown links.  The _substituteUidForSimpleType() function assumes
+   * it is given #2 but substitutes #1 if the name can be matched to a DocItem.
+   */
+  private _linkToUidIfPossible(typeName: string): string {
+    const docItem: DocItem | undefined = this._docItemsByTypeName.get(typeName.trim());
+    if (docItem) {
+      // Substitute the UID
+      return this._getUid(docItem);
+    }
+    return typeName;
+  }
+
   private _getYamlItemName(docItem: DocItem): string {
     if (docItem.parent && docItem.parent.kind === DocItemKind.Namespace) {
       // For members a namespace, show the full name excluding the package part:
