@microsoft/api-documenter - npm Package Compare versions

Comparing version 1.3.1 to 1.4.0

CHANGELOG.json

@@ -5,2 +5,14 @@ {
     {
+      "version": "1.4.0",
+      "tag": "@microsoft/api-documenter_v1.4.0",
+      "date": "Tue, 26 Jun 2018 23:54:17 GMT",
+      "comments": {
+        "minor": [
+          {
+            "comment": "The YAML target now automatically hyperlinks type references, but only if the type name is simple and not ambiguous"
+          }
+        ]
+      }
+    },
+    {
       "version": "1.3.1",
@@ -7,0 +19,0 @@ "tag": "@microsoft/api-documenter_v1.3.1",

CHANGELOG.md

 # Change Log - @microsoft/api-documenter
 
-This log was last generated on Tue, 26 Jun 2018 16:04:59 GMT and should not be manually modified.
+This log was last generated on Tue, 26 Jun 2018 23:54:17 GMT and should not be manually modified.
 
+## 1.4.0
+Tue, 26 Jun 2018 23:54:17 GMT
+
+### Minor changes
+
+- The YAML target now automatically hyperlinks type references, but only if the type name is simple and not ambiguous
+
 ## 1.3.1
@@ -6,0 +13,0 @@ Tue, 26 Jun 2018 16:04:59 GMT

lib/cli/BaseAction.js

@@ -42,3 +42,2 @@ "use strict";
         }
-        docItemSet.calculateReferences();
         return docItemSet;
@@ -45,0 +44,0 @@ }

lib/utils/DocItemSet.d.ts

@@ -46,2 +46,6 @@ import { ApiItem, IApiItemReference } from '@microsoft/api-extractor';
     tryGetChild(name: string): DocItem | undefined;
+    /**
+     * Visits this DocItem and every child DocItem in a preorder traversal.
+     */
+    forEach(callback: (docItem: DocItem) => void): void;
 }
@@ -73,5 +77,3 @@ /**
     readonly docPackages: DocItem[];
-    private _calculated;
     loadApiJsonFile(apiJsonFilename: string): void;
-    calculateReferences(): void;
     /**
@@ -82,3 +84,6 @@ * Attempts to find the DocItem described by an IApiItemReference.  If no matching item is
     resolveApiItemReference(reference: IApiItemReference): IDocItemSetResolveResult;
-    private _calculateReferences(docItem);
+    /**
+     * Visits every DocItem in the tree.
+     */
+    forEach(callback: (docItem: DocItem) => void): void;
 }

lib/utils/DocItemSet.js

@@ -138,2 +138,11 @@ "use strict";
     }
+    /**
+     * Visits this DocItem and every child DocItem in a preorder traversal.
+     */
+    forEach(callback) {
+        callback(this);
+        for (const child of this.children) {
+            child.forEach(callback);
+        }
+    }
 }
@@ -154,8 +163,4 @@ exports.DocItem = DocItem;
         this.docPackages = [];
-        this._calculated = false;
     }
     loadApiJsonFile(apiJsonFilename) {
-        if (this._calculated) {
-            throw new Error('calculateReferences() was already called');
-        }
         const apiPackage = api_extractor_1.ApiJsonFile.loadFromFile(apiJsonFilename);
@@ -166,10 +171,2 @@ const docItem = new DocItem(apiPackage, apiPackage.name, this, undefined);
     }
-    calculateReferences() {
-        if (this._calculated) {
-            return;
-        }
-        for (const docPackage of this.docPackages) {
-            this._calculateReferences(docPackage);
-        }
-    }
     /**
@@ -208,6 +205,8 @@ * Attempts to find the DocItem described by an IApiItemReference.  If no matching item is
     }
-    _calculateReferences(docItem) {
-        // (Calculate base classes and child classes)
-        for (const child of docItem.children) {
-            this._calculateReferences(child);
+    /**
+     * Visits every DocItem in the tree.
+     */
+    forEach(callback) {
+        for (const docPackage of this.docPackages) {
+            docPackage.forEach(callback);
         }
@@ -214,0 +213,0 @@ }

lib/yaml/YamlDocumenter.d.ts

@@ -9,2 +9,3 @@ import { DocItemSet } from '../utils/DocItemSet';
     private _docItemSet;
+    private _docItemsByTypeName;
     private _outputFolder;
@@ -35,2 +36,23 @@ constructor(docItemSet: DocItemSet);
     private _getUid(docItem);
+    /**
+     * Initialize the _docItemsByTypeName() data structure.
+     */
+    private _initDocItemsByTypeName();
+    /**
+     * 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);
+    /**
+     * If the docItem represents a scoped name such as "my-library:MyNamespace.MyClass",
+     * this returns a string such as "MyNamespace.MyClass".  If the result would not
+     * have at least one dot in it, then undefined is returned.
+     */
+    private _getTypeNameWithDot(docItem);
     private _getYamlItemName(docItem);
@@ -37,0 +59,0 @@ private _getYamlFilePath(docItem);

lib/yaml/YamlDocumenter.js

@@ -21,2 +21,4 @@ "use strict";
         this._docItemSet = docItemSet;
+        this._docItemsByTypeName = new Map();
+        this._initDocItemsByTypeName();
     }
@@ -267,3 +269,3 @@ generateFiles(outputFolder) {
             syntax.return = {
-                type: [apiMethod.returnValue.type],
+                type: [this._linkToUidIfPossible(apiMethod.returnValue.type)],
                 description: returnDescription
@@ -278,3 +280,3 @@ };
                 description: this._renderMarkdown(apiParameter.description, docItem),
-                type: [apiParameter.type || '']
+                type: [this._linkToUidIfPossible(apiParameter.type || '')]
             });
@@ -294,3 +296,3 @@ }
             syntax.return = {
-                type: [apiProperty.type]
+                type: [this._linkToUidIfPossible(apiProperty.type)]
             };
@@ -369,2 +371,75 @@ }
     }
+    /**
+     * Initialize the _docItemsByTypeName() data structure.
+     */
+    _initDocItemsByTypeName() {
+        // Collect the _docItemsByTypeName table
+        const ambiguousNames = new Set();
+        this._docItemSet.forEach((docItem) => {
+            switch (docItem.kind) {
+                case DocItemSet_1.DocItemKind.Class:
+                case DocItemSet_1.DocItemKind.Enum:
+                case DocItemSet_1.DocItemKind.Interface:
+                    // Attempt to register both the fully qualified name and the short name
+                    const namesForType = [docItem.name];
+                    // Note that nameWithDot cannot conflict with docItem.name (because docItem.name
+                    // cannot contain a dot)
+                    const nameWithDot = this._getTypeNameWithDot(docItem);
+                    if (nameWithDot) {
+                        namesForType.push(nameWithDot);
+                    }
+                    // Register all names
+                    for (const typeName of namesForType) {
+                        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);
+        }
+    }
+    /**
+     * 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.
+     */
+    _linkToUidIfPossible(typeName) {
+        // Note that typeName might be a _getTypeNameWithDot() name or it might be a simple class name
+        const docItem = this._docItemsByTypeName.get(typeName.trim());
+        if (docItem) {
+            // Substitute the UID
+            return this._getUid(docItem);
+        }
+        return typeName;
+    }
+    /**
+     * If the docItem represents a scoped name such as "my-library:MyNamespace.MyClass",
+     * this returns a string such as "MyNamespace.MyClass".  If the result would not
+     * have at least one dot in it, then undefined is returned.
+     */
+    _getTypeNameWithDot(docItem) {
+        const hierarchy = docItem.getHierarchy();
+        if (hierarchy.length > 0 && hierarchy[0].kind === DocItemSet_1.DocItemKind.Package) {
+            hierarchy.shift(); // ignore the package qualifier
+        }
+        if (hierarchy.length < 1) {
+            return undefined;
+        }
+        return hierarchy.map(x => x.name).join('.');
+    }
     _getYamlItemName(docItem) {
@@ -371,0 +446,0 @@ if (docItem.parent && docItem.parent.kind === DocItemSet_1.DocItemKind.Namespace) {

package.json

 {
   "name": "@microsoft/api-documenter",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Read JSON files from api-extractor, generate documentation pages",
@@ -5,0 +5,0 @@ "repository": {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

293140

increased by3.84%

Lines of code

3792

increased by3.04%

No dependency changes