Merge pull request microsoft#1515 from microsoft/octogonz/improve-docs

octogonz · web-flow · commit d44f4ecff15d · 2019-09-10T15:18:04.000-07:00
Update documentation
diff --git a/apps/api-documenter/README.md b/apps/api-documenter/README.md
@@ -2,16 +2,11 @@
 
 This tool can be used to generate an online API reference manual for your TypeScript library.
 It reads the *.api.json data files produced by [API Extractor](https://api-extractor.com/),
-and then generates web pages using the [Markdown](https://en.wikipedia.org/wiki/Markdown)
-file format.
+and then generates files in [Markdown](https://en.wikipedia.org/wiki/Markdown) or
+[DocFX](https://dotnet.github.io/docfx/) format.
 
-The **api-documenter** tool is part of Microsoft's production documentation pipeline.
-It is provided as a code sample to illustrate how to load and process the
-API JSON file format.  If your requirements are simple, you can use this tool directly.
-For more advanced scenarios, developers are encouraged to fork the project and modify
-the source code.  The implementation is intentionally kept simple and easy
-to understand.  This is possible because most of processing is already performed upstream
-by API Extractor.
+For usage information, see the
+[Generating Docs](https://api-extractor.com/pages/setup/generating_docs/) article from the API Extractor
+documentation.
 
-For more information, see the
-[Generating Docs](https://api-extractor.com/pages/setup/generating_docs/) article from the API Extractor documentation.
+API documentation for this package: https://rushstack.io/pages/api/api-documenter/
diff --git a/apps/api-documenter/src/index.ts b/apps/api-documenter/src/index.ts
@@ -1,6 +1,14 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+/**
+ * API Documenter generates an API reference website from the .api.json files created by API Extractor.
+ * The `@microsoft/api-documenter` package provides the command-line tool.  It also exposes a developer API that you
+ * can use to create plugins that customize how API Documenter generates documentation.
+ *
+ * @packageDocumentation
+ */
+
 export {
   IFeatureDefinition,
   IApiDocumenterPluginManifest
diff --git a/apps/api-extractor-model/README.md b/apps/api-extractor-model/README.md
@@ -1,11 +1,10 @@
 # @microsoft/api-extractor-model
 
-This library is used with the [@microsoft/api-extractor](https://www.npmjs.com/package/@microsoft/api-extractor).
-For documentation and other information about the API Extractor tool, please visit the
-[web site](https://api-extractor.com/).
+Use this library to read and write *.api.json files as defined by the [API Extractor](https://api-extractor.com/) tool.
+These files are used to generate a documentation website for your TypeScript package.  The files store the
+API signatures and doc comments that were extracted from your package.
 
-The **@microsoft/api-extractor-model** library is used to read and write the *.api.json data file format,
-which stores information about the exported API signatures for a TypeScript project.
+API documentation for this package: https://rushstack.io/pages/api/api-extractor-model/
 
 ## Example Usage
 
@@ -56,5 +55,5 @@ to extend more than one base class).  The "mixin" is a TypeScript merged declara
 the function that generates a subclass, an interface that describes the members of the subclass, and
 a namespace containing static members of the class.
 
-> For a complete example that shows how to uset these APIs to generate an API reference web site,
+> For a complete project that uses these APIs to generate an API reference web site,
 > see the [@microsoft/api-documenter](https://www.npmjs.com/package/@microsoft/api-documenter) source code.
diff --git a/apps/api-extractor-model/src/index.ts b/apps/api-extractor-model/src/index.ts
@@ -2,9 +2,10 @@
 // See LICENSE in the project root for license information.
 
 /**
- * API Extractor helps you build better TypeScript library packages.
- * It helps with validation, documentation, and reviewing of the exported API
- * for a TypeScript library.
+ * Use this library to read and write *.api.json files as defined by the
+ * {@link https://api-extractor.com/ | API Extractor}  tool.  These files are used to generate a documentation
+ * website for your TypeScript package.  The files store the API signatures and doc comments that were extracted
+ * from your package.
  *
  * @packageDocumentation
  */
diff --git a/apps/api-extractor/README.md b/apps/api-extractor/README.md
@@ -40,3 +40,5 @@ Best of all, **API Extractor** is free and open source.  Join the community and
 # Getting Started
 
 For more details and support resources, please visit: https://api-extractor.com/
+
+API documentation for this package: https://rushstack.io/pages/api/api-extractor/
diff --git a/apps/api-extractor/src/index.ts b/apps/api-extractor/src/index.ts
@@ -2,9 +2,9 @@
 // See LICENSE in the project root for license information.
 
 /**
- * API Extractor helps you build better TypeScript library packages.
- * It helps with validation, documentation, and reviewing of the exported API
- * for a TypeScript library.
+ * API Extractor helps with validation, documentation, and reviewing of the exported API for a TypeScript library.
+ * The `@microsoft/api-extractor` package provides the command-line tool.  It also exposes a developer API that you
+ * can use to invoke API Extractor programmatically.
  *
  * @packageDocumentation
  */
diff --git a/apps/rush-lib/README.md b/apps/rush-lib/README.md
@@ -12,3 +12,5 @@ might interfere with the globally installed Rush).
 
 The **@microsoft/rush** version number is always exactly equal
 to the **@microsoft/rush-lib** version number that it depends on.
+
+API documentation for this package: https://rushstack.io/pages/api/rush-lib/
diff --git a/apps/rush-lib/src/index.ts b/apps/rush-lib/src/index.ts
@@ -2,7 +2,7 @@
 // See LICENSE in the project root for license information.
 
 /**
- * A library for writing scripts that interact with the Rush tool.
+ * A library for writing scripts that interact with the {@link https://rushjs.io/ | Rush} tool.
  * @packageDocumentation
  */
 
diff --git a/common/changes/@microsoft/api-documenter/octogonz-improve-docs_2019-09-08-04-25.json b/common/changes/@microsoft/api-documenter/octogonz-improve-docs_2019-09-08-04-25.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-documenter",
+      "comment": "Update documentation",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/api-documenter",
+  "email": "4673363+octogonz@users.noreply.github.com"
+}
diff --git a/common/changes/@microsoft/api-extractor-model/octogonz-improve-docs_2019-09-08-04-25.json b/common/changes/@microsoft/api-extractor-model/octogonz-improve-docs_2019-09-08-04-25.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor-model",
+      "comment": "Update documentation",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor-model",
+  "email": "4673363+octogonz@users.noreply.github.com"
+}
diff --git a/common/changes/@microsoft/api-extractor/octogonz-improve-docs_2019-09-08-04-25.json b/common/changes/@microsoft/api-extractor/octogonz-improve-docs_2019-09-08-04-25.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "comment": "Update documentation",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor",
+  "email": "4673363+octogonz@users.noreply.github.com"
+}
diff --git a/common/changes/@microsoft/node-core-library/octogonz-improve-docs_2019-09-08-04-25.json b/common/changes/@microsoft/node-core-library/octogonz-improve-docs_2019-09-08-04-25.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/node-core-library",
+      "comment": "Update documentation",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/node-core-library",
+  "email": "4673363+octogonz@users.noreply.github.com"
+}
diff --git a/common/changes/@microsoft/package-deps-hash/octogonz-improve-docs_2019-09-08-04-25.json b/common/changes/@microsoft/package-deps-hash/octogonz-improve-docs_2019-09-08-04-25.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/package-deps-hash",
+      "comment": "Update documentation",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/package-deps-hash",
+  "email": "4673363+octogonz@users.noreply.github.com"
+}
diff --git a/common/changes/@microsoft/rush/octogonz-improve-docs_2019-09-08-04-25.json b/common/changes/@microsoft/rush/octogonz-improve-docs_2019-09-08-04-25.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Update documentation",
+      "packageName": "@microsoft/rush",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush",
+  "email": "4673363+octogonz@users.noreply.github.com"
+}
diff --git a/common/changes/@microsoft/stream-collator/octogonz-improve-docs_2019-09-08-04-25.json b/common/changes/@microsoft/stream-collator/octogonz-improve-docs_2019-09-08-04-25.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/stream-collator",
+      "comment": "Update documentation",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/stream-collator",
+  "email": "4673363+octogonz@users.noreply.github.com"
+}
diff --git a/common/changes/@microsoft/ts-command-line/octogonz-improve-docs_2019-09-08-04-25.json b/common/changes/@microsoft/ts-command-line/octogonz-improve-docs_2019-09-08-04-25.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/ts-command-line",
+      "comment": "Update documentation",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/ts-command-line",
+  "email": "4673363+octogonz@users.noreply.github.com"
+}
diff --git a/common/reviews/api/api-documenter.api.md b/common/reviews/api/api-documenter.api.md
@@ -82,6 +82,4 @@ export class PluginFeatureInitialization {
 }
 
 
-// (No @packageDocumentation comment for this package)
-
 ```
diff --git a/common/reviews/api/package-deps-hash.api.md b/common/reviews/api/package-deps-hash.api.md
@@ -7,15 +7,13 @@
 // @public
 export function getPackageDeps(packagePath?: string, excludedPaths?: string[]): IPackageDeps;
 
-// @public (undocumented)
+// @public
 export interface IPackageDeps {
-    // (undocumented)
+    arguments?: string;
     files: {
         [key: string]: string;
     };
 }
 
 
-// (No @packageDocumentation comment for this package)
-
 ```
diff --git a/common/reviews/api/stream-collator.api.md b/common/reviews/api/stream-collator.api.md
@@ -30,6 +30,4 @@ export interface ITaskWriter {
 }
 
 
-// (No @packageDocumentation comment for this package)
-
 ```
diff --git a/libraries/node-core-library/README.md b/libraries/node-core-library/README.md
@@ -27,3 +27,5 @@ This package is NOT intended to be a dumping ground for arbitrary utilities
 that seem like they might be useful.  Code should start somewhere else, and
 then graduate to **node-core-library** after its value has already been
 demonstrated.  If in doubt, create your own NPM package.
+
+API documentation for this package: https://rushstack.io/pages/api/node-core-library/
diff --git a/libraries/package-deps-hash/README.md b/libraries/package-deps-hash/README.md
@@ -1,44 +1,32 @@
 # @microsoft/package-deps-hash
 
-`package-deps-hash` is a general utility for building a JSON object containing the git hashes of all files used to produce a given package. Only
-files in a git repo that are not in .gitignore will be considered in building the hash.
+The `package-deps-hash` library generates a JSON object containing the git hashes of all files used to produce
+a given package.  This is useful for scenarios where you want to define a "change receipt" file to be published
+with a package.  The [Rush](https://rushjs.io/) tool uses this library to implement incremental build detection.
 
-This utility is useful for scenarios where you want to define a "change receipt" file to be published with a package. The file content
-and the current state of the package can be compared then to determine if the package needs to be rebuilt.
+Only files in a git repo that are not in .gitignore will be considered in building the hash.  The file content and
+the current state of the package can be compared then to determine whether the package needs to be rebuilt.
 
-Internally it uses the GIT hashes to derive the hashes for package content. This allows the process to piggyback off GIT's hashing
-optimizations, as opposed to creating a more elaborate diffing scheme.
+Internally it uses the GIT hashes to derive the hashes for package content. This allows the process to leverage Git's
+hash optimizations, as opposed to creating a more elaborate diffing scheme.
 
-NOTE: GIT is required to be accessible in the command line path.
+NOTE: Git is required to be accessible in the command line path.
 
 ## Usage
 
-
-```
+```ts
 let _ = require('lodash');
 let { getPackageDeps } = require('@microsoft/package-deps-hash');
 
 // Gets the current deps object for the current working directory
 let deps = getPackageDeps();
-let existingDeps = JSON.parse(fs.readFileSync('deps.json));
+let existingDeps = JSON.parse(fs.readFileSync('package-deps.json'));
 
 if (_.isEqual(deps, existingDeps)) {
   // Skip re-building package.
 } else {
   // Rebuild package.
 }
-
 ```
 
-## API
----
-### getPackageDeps(packageFolderPath, exclusions)
-
-Gets an object containing all of the file hashes.
-
-#### Parameters
-|name|type|description|
-|----|----|-----------|
-|packageFolderPath|(string, optional, default: cwd())|The folder path to derive the package dependencies from. This is typically the folder containing package.json.|
-|exclusions| (string[], optional)|An optional array of file path exclusions. If a file should be omitted from the list of dependencies, use this to exclude it.|
-
+API documentation for this package: https://rushstack.io/pages/api/package-deps-hash/
diff --git a/libraries/package-deps-hash/src/IPackageDeps.ts b/libraries/package-deps-hash/src/IPackageDeps.ts
@@ -1,7 +1,18 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
-/** @public */
+/**
+ * The data structure returned by {@link getPackageDeps}.
+ * @public
+ */
 export interface IPackageDeps {
+  /**
+   * The `key` is a source file path, relative to the package folder.  The value is the Git hash.
+   */
   files: { [key: string]: string };
+
+  /**
+   * An optional field used to story command-line arguments for the build.
+   */
+  arguments?: string;
 }
diff --git a/libraries/package-deps-hash/src/getPackageDeps.ts b/libraries/package-deps-hash/src/getPackageDeps.ts
@@ -128,7 +128,13 @@ export function gitStatus(path: string): string {
 }
 
 /**
- * Collects the current git filehashes for a directory
+ * Builds an object containing hashes for the files under the specified `packagePath` folder.
+ * @param packagePath - The folder path to derive the package dependencies from. This is typically the folder
+ *                      containing package.json.  If omitted, the default value is the current working directory.
+ * @param excludedPaths - An optional array of file path exclusions. If a file should be omitted from the list
+ *                         of dependencies, use this to exclude it.
+ * @returns the package-deps.json file content
+ *
  * @public
  */
 export function getPackageDeps(packagePath: string = process.cwd(), excludedPaths?: string[]): IPackageDeps {
diff --git a/libraries/package-deps-hash/src/index.ts b/libraries/package-deps-hash/src/index.ts
@@ -1,5 +1,17 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+/**
+ * This package builds a JSON object containing the git hashes of all files used to produce a given NPM package.
+ * The {@link https://rushjs.io/ | Rush} tool uses this library to implement incremental build detection.
+ *
+ * @remarks
+ *
+ * For more info, please see the package {@link https://www.npmjs.com/package/@microsoft/package-deps-hash
+ * | README}.
+ *
+ * @packageDocumentation
+ */
+
 export { getPackageDeps } from './getPackageDeps';
 export { IPackageDeps } from './IPackageDeps';
diff --git a/libraries/stream-collator/README.md b/libraries/stream-collator/README.md
diff --git a/libraries/stream-collator/src/index.ts b/libraries/stream-collator/src/index.ts
diff --git a/libraries/ts-command-line/README.md b/libraries/ts-command-line/README.md
