docs(packages): add api-extractor to public packages (#4747)

MYoung25 · web-flow · commit 20cda3fcf302 · 2023-05-23T10:55:57.000-04:00
* docs(packages): add api-extractor to public packages

* docs(abort-controller): add api-extractor to abort-controller
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -8,7 +8,7 @@ module.exports = {
     // Uses the recommended rules from the @typescript-eslint/eslint-plugin
     "plugin:@typescript-eslint/recommended",
   ],
-  plugins: ["@typescript-eslint", "simple-import-sort", "eslint-plugin-sort-export-all"],
+  plugins: ["@typescript-eslint", "simple-import-sort", "eslint-plugin-sort-export-all", "eslint-plugin-tsdoc"],
   rules: {
     /** Turn off strict enforcement */
     "@typescript-eslint/ban-types": "off",
@@ -23,6 +23,7 @@ module.exports = {
 
     /** Warnings */
     "@typescript-eslint/no-namespace": "warn",
+    "tsdoc/syntax": "warn",
 
     /** Errors */
     "simple-import-sort/imports": "error",
diff --git a/.gitignore b/.gitignore
@@ -65,6 +65,8 @@ benchmark/size/raw
 
 etc/
 temp/
+temp-packages/
+temp-lib/
 
 # Gradle composite build properties
 codegen/local.properties
diff --git a/api-extractor.json b/api-extractor.json
@@ -60,9 +60,7 @@
    * This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been
    * local files for library1.
    */
-  "bundledPackages": [
-    // "@aws-sdk/types", "@aws-sdk/util-waiter", "@aws-sdk/smithy-client"
-  ],
+  // "bundledPackages": ["@aws-sdk/types", "@aws-sdk/util-waiter", "@aws-sdk/smithy-client", "@aws-smithy/types"],
 
   /**
    * Specifies what type of newlines API Extractor should use when writing output files.  By default, the output files
@@ -178,7 +176,7 @@
      * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
      * DEFAULT VALUE: "<projectFolder>/temp/"
      */
-    "reportTempFolder": "./temp/"
+    "reportTempFolder": "./temp/",
 
     /**
      * Whether "forgotten exports" should be included in the API report file. Forgotten exports are declarations
@@ -187,7 +185,7 @@
      *
      * DEFAULT VALUE: "false"
      */
-    // "includeForgottenExports": false
+    "includeForgottenExports": true
   },
 
   /**
@@ -217,7 +215,7 @@
      *
      * DEFAULT VALUE: "false"
      */
-    // "includeForgottenExports": false,
+    // "includeForgottenExports": true
 
     /**
      * The base URL where the project's source code can be viewed on a website such as GitHub or
@@ -243,7 +241,7 @@
     /**
      * (REQUIRED) Whether to generate the .d.ts rollup file.
      */
-    "enabled": true
+    "enabled": false,
 
     /**
      * Specifies the output path for a .d.ts rollup file to be generated without any trimming.
@@ -257,7 +255,7 @@
      * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
      * DEFAULT VALUE: "<projectFolder>/dist/<unscopedPackageName>.d.ts"
      */
-    // "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
+    "untrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
 
     /**
      * Specifies the output path for a .d.ts rollup file to be generated with trimming for an "alpha" release.
diff --git a/api-extractor.packages.json b/api-extractor.packages.json
@@ -0,0 +1,10 @@
+{
+  "extends": "./api-extractor.json",
+  "docModel": {
+    "apiJsonFilePath": "./temp-packages/<unscopedPackageName>.api.json"
+  },
+  "apiReport": {
+    "reportFolder": "./temp-packages/",
+    "reportTempFolder": "./temp-packages/"
+  }
+}
diff --git a/packages/abort-controller/api-extractor.json b/packages/abort-controller/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/abort-controller/package.json b/packages/abort-controller/package.json
@@ -13,6 +13,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest"
   },
   "author": {
diff --git a/packages/cloudfront-signer/api-extractor.json b/packages/cloudfront-signer/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/cloudfront-signer/package.json b/packages/cloudfront-signer/package.json
@@ -9,6 +9,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest"
   },
   "main": "./dist-cjs/index.js",
diff --git a/packages/credential-providers/api-extractor.json b/packages/credential-providers/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/credential-providers/package.json b/packages/credential-providers/package.json
@@ -15,6 +15,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest"
   },
   "keywords": [
diff --git a/packages/fetch-http-handler/api-extractor.json b/packages/fetch-http-handler/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/fetch-http-handler/package.json b/packages/fetch-http-handler/package.json
@@ -10,6 +10,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest --coverage && karma start karma.conf.js"
   },
   "author": {
diff --git a/packages/hash-node/api-extractor.json b/packages/hash-node/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/hash-node/package.json b/packages/hash-node/package.json
@@ -9,6 +9,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest"
   },
   "main": "./dist-cjs/index.js",
diff --git a/packages/middleware-bucket-endpoint/api-extractor.json b/packages/middleware-bucket-endpoint/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/middleware-bucket-endpoint/package.json b/packages/middleware-bucket-endpoint/package.json
@@ -9,6 +9,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest"
   },
   "main": "./dist-cjs/index.js",
diff --git a/packages/middleware-endpoint/api-extractor.json b/packages/middleware-endpoint/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/middleware-endpoint/package.json b/packages/middleware-endpoint/package.json
@@ -9,6 +9,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest --passWithNoTests",
     "test:integration": "jest -c jest.config.integ.js"
   },
diff --git a/packages/middleware-retry/api-extractor.json b/packages/middleware-retry/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/middleware-retry/package.json b/packages/middleware-retry/package.json
@@ -9,6 +9,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest",
     "test:integration": "jest -c jest.config.integ.js"
   },
diff --git a/packages/middleware-stack/api-extractor.json b/packages/middleware-stack/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/middleware-stack/package.json b/packages/middleware-stack/package.json
@@ -10,6 +10,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest",
     "test:integration": "jest -c jest.config.integ.js --passWithNoTests"
   },
diff --git a/packages/node-http-handler/api-extractor.json b/packages/node-http-handler/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/node-http-handler/package.json b/packages/node-http-handler/package.json
@@ -10,6 +10,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest --coverage"
   },
   "author": {
diff --git a/packages/polly-request-presigner/api-extractor.json b/packages/polly-request-presigner/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/polly-request-presigner/package.json b/packages/polly-request-presigner/package.json
@@ -9,6 +9,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest"
   },
   "main": "./dist-cjs/index.js",
diff --git a/packages/rds-signer/api-extractor.json b/packages/rds-signer/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/rds-signer/package.json b/packages/rds-signer/package.json
@@ -13,6 +13,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest"
   },
   "engines": {
diff --git a/packages/s3-presigned-post/api-extractor.json b/packages/s3-presigned-post/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/s3-presigned-post/package.json b/packages/s3-presigned-post/package.json
@@ -9,6 +9,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest",
     "test:e2e": "jest -c jest.config.e2e.js"
   },
diff --git a/packages/s3-request-presigner/api-extractor.json b/packages/s3-request-presigner/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/s3-request-presigner/package.json b/packages/s3-request-presigner/package.json
@@ -9,6 +9,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest"
   },
   "main": "./dist-cjs/index.js",
diff --git a/packages/shared-ini-file-loader/api-extractor.json b/packages/shared-ini-file-loader/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/shared-ini-file-loader/package.json b/packages/shared-ini-file-loader/package.json
@@ -22,6 +22,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest"
   },
   "author": {
diff --git a/packages/signature-v4-crt/api-extractor.json b/packages/signature-v4-crt/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/signature-v4-crt/package.json b/packages/signature-v4-crt/package.json
@@ -13,6 +13,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest --coverage"
   },
   "author": {
diff --git a/packages/signature-v4-multi-region/api-extractor.json b/packages/signature-v4-multi-region/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/signature-v4-multi-region/package.json b/packages/signature-v4-multi-region/package.json
@@ -9,6 +9,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest"
   },
   "main": "./dist-cjs/index.js",
diff --git a/packages/signature-v4/api-extractor.json b/packages/signature-v4/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/signature-v4/package.json b/packages/signature-v4/package.json
@@ -13,6 +13,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest --coverage"
   },
   "author": {
diff --git a/packages/smithy-client/api-extractor.json b/packages/smithy-client/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/smithy-client/package.json b/packages/smithy-client/package.json
@@ -9,6 +9,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest --passWithNoTests"
   },
   "main": "./dist-cjs/index.js",
diff --git a/packages/token-providers/api-extractor.json b/packages/token-providers/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/token-providers/package.json b/packages/token-providers/package.json
@@ -13,6 +13,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest"
   },
   "keywords": [
diff --git a/packages/types/api-extractor.json b/packages/types/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/types/package.json b/packages/types/package.json
@@ -13,6 +13,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "tsc -p tsconfig.test.json"
   },
   "author": {
diff --git a/packages/util-create-request/api-extractor.json b/packages/util-create-request/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/util-create-request/package.json b/packages/util-create-request/package.json
@@ -9,6 +9,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest"
   },
   "main": "./dist-cjs/index.js",
diff --git a/packages/util-dynamodb/api-extractor.json b/packages/util-dynamodb/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/util-dynamodb/package.json b/packages/util-dynamodb/package.json
@@ -9,6 +9,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
     "clean": "rimraf ./dist-* && rimraf *.tsbuildinfo",
+    "extract:docs": "api-extractor run --local",
     "test": "jest"
   },
   "main": "./dist-cjs/index.js",
diff --git a/packages/util-retry/api-extractor.json b/packages/util-retry/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/util-retry/package.json b/packages/util-retry/package.json
diff --git a/packages/xhr-http-handler/api-extractor.json b/packages/xhr-http-handler/api-extractor.json
diff --git a/packages/xhr-http-handler/package.json b/packages/xhr-http-handler/package.json

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +{
 +  "extends": "../../api-extractor.packages.json",
 +  "mainEntryPointFilePath": "./dist-types/index.d.ts"
 +}