@microsoft/api-extractor-model - npm Package Compare versions

Comparing version 7.12.5 to 7.13.0

CHANGELOG.json

@@ -5,2 +5,14 @@ {
     {
+      "version": "7.13.0",
+      "tag": "@microsoft/api-extractor-model_v7.13.0",
+      "date": "Tue, 20 Apr 2021 04:59:51 GMT",
+      "comments": {
+        "minor": [
+          {
+            "comment": "The .api.json file format now stores the TSDoc configuration used for parsing doc comments"
+          }
+        ]
+      }
+    },
+    {
       "version": "7.12.5",
@@ -7,0 +19,0 @@ "tag": "@microsoft/api-extractor-model_v7.12.5",

CHANGELOG.md

 # Change Log - @microsoft/api-extractor-model
 
-This log was last generated on Mon, 12 Apr 2021 15:10:28 GMT and should not be manually modified.
+This log was last generated on Tue, 20 Apr 2021 04:59:51 GMT and should not be manually modified.
 
+## 7.13.0
+Tue, 20 Apr 2021 04:59:51 GMT
+
+### Minor changes
+
+- The .api.json file format now stores the TSDoc configuration used for parsing doc comments
+
 ## 7.12.5
@@ -6,0 +13,0 @@ Mon, 12 Apr 2021 15:10:28 GMT

lib/aedoc/AedocDefinitions.d.ts

 import { TSDocConfiguration, TSDocTagDefinition } from '@microsoft/tsdoc';
 /**
  * @internal
+ * @deprecated - tsdoc configuration is now constructed from tsdoc.json files associated with each package.
  */
@@ -5,0 +6,0 @@ export declare class AedocDefinitions {

lib/aedoc/AedocDefinitions.js

@@ -9,2 +9,3 @@ "use strict";
  * @internal
+ * @deprecated - tsdoc configuration is now constructed from tsdoc.json files associated with each package.
  */
@@ -11,0 +12,0 @@ class AedocDefinitions {

lib/items/ApiDocumentedItem.js

@@ -27,3 +27,2 @@ "use strict";
 const ApiItem_1 = require("./ApiItem");
-const AedocDefinitions_1 = require("../aedoc/AedocDefinitions");
 /**
@@ -49,3 +48,3 @@ * An abstract base class for API declarations that can have an associated TSDoc comment.
         if (documentedJson.docComment) {
-            const tsdocParser = new tsdoc.TSDocParser(AedocDefinitions_1.AedocDefinitions.tsdocConfiguration);
+            const tsdocParser = new tsdoc.TSDocParser(context.tsdocConfiguration);
             // NOTE: For now, we ignore TSDoc errors found in a serialized .api.json file.
@@ -52,0 +51,0 @@ // Normally these errors would have already been reported by API Extractor during analysis.

lib/model/ApiPackage.d.ts

 import { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference';
 import { ApiItemKind, IApiItemJson } from '../items/ApiItem';
 import { ApiItemContainerMixin, IApiItemContainerMixinOptions } from '../mixins/ApiItemContainerMixin';
-import { IJsonFileSaveOptions } from '@rushstack/node-core-library';
+import { IJsonFileSaveOptions, JsonObject } from '@rushstack/node-core-library';
 import { ApiDocumentedItem, IApiDocumentedItemOptions } from '../items/ApiDocumentedItem';
@@ -9,2 +9,3 @@ import { ApiEntryPoint } from './ApiEntryPoint';
 import { ApiJsonSchemaVersion } from './DeserializerContext';
+import { TSDocConfiguration } from '@microsoft/tsdoc';
 /**
@@ -15,2 +16,3 @@ * Constructor options for {@link ApiPackage}.
 export interface IApiPackageOptions extends IApiItemContainerMixinOptions, IApiNameMixinOptions, IApiDocumentedItemOptions {
+    tsdocConfiguration: TSDocConfiguration;
 }
@@ -48,2 +50,12 @@ export interface IApiPackageMetadataJson {
     oldestForwardsCompatibleVersion?: ApiJsonSchemaVersion;
+    /**
+     * The TSDoc configuration that was used when analyzing the API for this package.
+     *
+     * @remarks
+     *
+     * The structure of this objet is defined by the `@microsoft/tsdoc-config` library.
+     * Normally this configuration is loaded from the project's tsdoc.json file.  It is stored
+     * in the .api.json file so that doc comments can be parsed accurately when loading the file.
+     */
+    tsdocConfig: JsonObject;
 }
@@ -92,2 +104,3 @@ export interface IApiPackageJson extends IApiItemJson {
 export declare class ApiPackage extends ApiPackage_base {
+    private readonly _tsdocConfiguration;
     constructor(options: IApiPackageOptions);
@@ -100,2 +113,11 @@ static loadFromJsonFile(apiJsonFilename: string): ApiPackage;
     get entryPoints(): ReadonlyArray<ApiEntryPoint>;
+    /**
+     * The TSDoc configuration that was used when analyzing the API for this package.
+     *
+     * @remarks
+     *
+     * Normally this configuration is loaded from the project's tsdoc.json file.  It is stored
+     * in the .api.json file so that doc comments can be parsed accurately when loading the file.
+     */
+    get tsdocConfiguration(): TSDocConfiguration;
     /** @override */
@@ -102,0 +124,0 @@ addMember(member: ApiEntryPoint): void;

lib/model/ApiPackage.js

@@ -13,2 +13,4 @@ "use strict";
 const DeserializerContext_1 = require("./DeserializerContext");
+const tsdoc_1 = require("@microsoft/tsdoc");
+const tsdoc_config_1 = require("@microsoft/tsdoc-config");
 /**
@@ -27,2 +29,3 @@ * Represents an NPM package containing API declarations.
         super(options);
+        this._tsdocConfiguration = options.tsdocConfiguration;
     }
@@ -62,2 +65,10 @@ static loadFromJsonFile(apiJsonFilename) {
         }
+        const tsdocConfiguration = new tsdoc_1.TSDocConfiguration();
+        if (versionToDeserialize >= DeserializerContext_1.ApiJsonSchemaVersion.V_1004) {
+            const tsdocConfigFile = tsdoc_config_1.TSDocConfigFile.loadFromObject(jsonObject.metadata.tsdocConfig);
+            if (tsdocConfigFile.hasErrors) {
+                throw new Error(`Error loading ${apiJsonFilename}:\n` + tsdocConfigFile.getErrorSummary());
+            }
+            tsdocConfigFile.configureParser(tsdocConfiguration);
+        }
         const context = new DeserializerContext_1.DeserializerContext({
@@ -67,3 +78,4 @@ apiJsonFilename,
             toolVersion: jsonObject.metadata.toolVersion,
-            versionToDeserialize: versionToDeserialize
+            versionToDeserialize: versionToDeserialize,
+            tsdocConfiguration
         });
@@ -84,2 +96,13 @@ return ApiItem_1.ApiItem.deserialize(jsonObject, context);
     }
+    /**
+     * The TSDoc configuration that was used when analyzing the API for this package.
+     *
+     * @remarks
+     *
+     * Normally this configuration is loaded from the project's tsdoc.json file.  It is stored
+     * in the .api.json file so that doc comments can be parsed accurately when loading the file.
+     */
+    get tsdocConfiguration() {
+        return this._tsdocConfiguration;
+    }
     /** @override */
@@ -100,2 +123,4 @@ addMember(member) {
         const packageJson = node_core_library_1.PackageJsonLookup.loadOwnPackageJson(__dirname);
+        const tsdocConfigFile = tsdoc_config_1.TSDocConfigFile.loadFromParser(this.tsdocConfiguration);
+        const tsdocConfig = tsdocConfigFile.saveToObject();
         const jsonObject = {
@@ -108,3 +133,4 @@ metadata: {
                 schemaVersion: DeserializerContext_1.ApiJsonSchemaVersion.LATEST,
-                oldestForwardsCompatibleVersion: DeserializerContext_1.ApiJsonSchemaVersion.OLDEST_FORWARDS_COMPATIBLE
+                oldestForwardsCompatibleVersion: DeserializerContext_1.ApiJsonSchemaVersion.OLDEST_FORWARDS_COMPATIBLE,
+                tsdocConfig
             }
@@ -111,0 +137,0 @@ };

lib/model/DeserializerContext.d.ts

@@ -0,1 +1,2 @@
+import { TSDocConfiguration } from '@microsoft/tsdoc';
 export declare enum ApiJsonSchemaVersion {
@@ -22,2 +23,9 @@ /**
     /**
+     * Add a "tsdocConfig" field that tracks the TSDoc configuration for parsing doc comments.
+     *
+     * This is not a breaking change because an older implementation will still work correctly.  The
+     * custom tags will be skipped over by the parser.
+     */
+    V_1004 = 1004,
+    /**
      * The current latest .api.json schema version.
@@ -28,3 +36,3 @@ *
      */
-    LATEST = 1003,
+    LATEST = 1004,
     /**
@@ -63,4 +71,8 @@ * The oldest .api.json schema version that is still supported for backwards compatibility.
     readonly versionToDeserialize: ApiJsonSchemaVersion;
+    /**
+     * The TSDoc configuration for the context.
+     */
+    readonly tsdocConfiguration: TSDocConfiguration;
     constructor(options: DeserializerContext);
 }
 //# sourceMappingURL=DeserializerContext.d.ts.map

lib/model/DeserializerContext.js

@@ -28,2 +28,9 @@ "use strict";
     /**
+     * Add a "tsdocConfig" field that tracks the TSDoc configuration for parsing doc comments.
+     *
+     * This is not a breaking change because an older implementation will still work correctly.  The
+     * custom tags will be skipped over by the parser.
+     */
+    ApiJsonSchemaVersion[ApiJsonSchemaVersion["V_1004"] = 1004] = "V_1004";
+    /**
      * The current latest .api.json schema version.
@@ -34,3 +41,3 @@ *
      */
-    ApiJsonSchemaVersion[ApiJsonSchemaVersion["LATEST"] = 1003] = "LATEST";
+    ApiJsonSchemaVersion[ApiJsonSchemaVersion["LATEST"] = 1004] = "LATEST";
     /**
@@ -58,2 +65,3 @@ * The oldest .api.json schema version that is still supported for backwards compatibility.
         this.versionToDeserialize = options.versionToDeserialize;
+        this.tsdocConfiguration = options.tsdocConfiguration;
     }
@@ -60,0 +68,0 @@ }

package.json

 {
 	"name": "@microsoft/api-extractor-model",
-	"version": "7.12.5",
+	"version": "7.13.0",
 	"description": "A helper library for loading and saving the .api.json files created by API Extractor",
@@ -17,3 +17,4 @@ "repository": {
 	"dependencies": {
-		"@microsoft/tsdoc": "0.12.24",
+		"@microsoft/tsdoc": "0.13.2",
+		"@microsoft/tsdoc-config": "~0.15.2",
 		"@rushstack/node-core-library": "3.36.2"
@@ -20,0 +21,0 @@ },

No alert changes

Improved metrics

Total package byte prevSize

670323

increased by1.27%

Lines of code

9274

increased by1.13%

Worsened metrics

Dependency count

3

increased by50%

Dependency changes

• + Added@microsoft/tsdoc-config@~0.15.2

• + Added@microsoft/tsdoc@0.13.2(transitive)

• + Added@microsoft/tsdoc-config@0.15.2(transitive)

• + Addedajv@6.12.6(transitive)

• + Addedfast-deep-equal@3.1.3(transitive)

• + Addedfast-json-stable-stringify@2.1.0(transitive)

• + Addedfunction-bind@1.1.2(transitive)

• + Addedhasown@2.0.2(transitive)

• + Addedis-core-module@2.16.1(transitive)

• + Addedjson-schema-traverse@0.4.1(transitive)

• + Addedpunycode@2.3.1(transitive)

• + Addedresolve@1.19.0(transitive)

• + Addeduri-js@4.4.1(transitive)

• - Removed@microsoft/tsdoc@0.12.24(transitive)

• Updated@microsoft/tsdoc@0.13.2