Tune up package documentation, add links to the new API reference web…

…site

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/

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

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.

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
  */

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/

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
  */

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/

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
  */
 

common/reviews/api/api-documenter.api.md

@@ -82,6 +82,4 @@ export class PluginFeatureInitialization {
 }
 
 
-// (No @packageDocumentation comment for this package)
-
 ```

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)
-
 ```

common/reviews/api/stream-collator.api.md

@@ -30,6 +30,4 @@ export interface ITaskWriter {
 }
 
 
-// (No @packageDocumentation comment for this package)
-
 ```

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/

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/

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;
 }

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 {

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';

libraries/stream-collator/README.md

@@ -1,11 +1,14 @@
 ## stream-collator
 
-Oftentimes, when working with multiple parallel asynchronous processes, it is helpful to ensure that their
-outputs are not mixed together, as this can cause readability issues in the console or log. The
-**stream-collator** manages the output of these streams carefully, such that no two streams are writing
-at the same time. At any given time, one stream registered with the collator is the **active stream**
-which means that particular stream will be live streaming, while the others will wait for that stream
-to finish before their completion.
+This library enables a tool to display live console output from multiple asynchronous processes,
+while ensuring that their output does not get jumbled together.
+
+## How does it work?
+
+The **stream-collator** manages the output of these streams, ensuring that no two streams are writing to the console
+at the same time. At any given time, one stream registered with the collator is the **active stream**, which means
+that particular stream will be live streaming, while the others will wait for that stream to finish before their
+output is displayed.
 
 For example, if you have 3 streams (e.g. from using `child_process.spawn()`).
 
@@ -15,24 +18,24 @@ Stream B will write: `BBBBBBBBBBBBBBBBBBBB`
 
 Stream C will write: `CCCCCCCCCC`
 
-If these streams are all being piped directly to stdout, you could end up with something like:
+If these streams are all being piped directly to stdout (without stream-collator), you could end up with jumbled
+output:
 
 `ABACCCBCCCCBBABBCBBABBBBBBCCAB`
 
-**Yikes!**
-
-Most likely, something like the following would be much more useful to users of your application:
+Something like the following would be much more useful to users of your application:
 
 `AAAAABBBBBBBBBBBBBBBCCCCCCCCCC`
 
-This is where the **stream-collator** comes in handy!
+This is where the **stream-collator** comes in!
 
-## Installation
+## Usage
 
 Install the stream-collator:
 
 `npm install --save @microsoft/stream-collator`
 
+
 Import the collator:
 
 ```javascript
@@ -43,8 +46,6 @@ import StreamCollator from '@microsoft/stream-collator'; // es6
 const StreamCollator = require('@microsoft/stream-collator'); // commonjs
 ```
 
-## Usage
-
 A stream collator adheres to the [NodeJS Stream API](https://nodejs.org/api/stream.html), meaning that it effectively
 is special type of [ReadableStream](https://nodejs.org/api/stream.html#stream_class_stream_readable). This makes
 working with the stream collator very simple. Imagine we had the 3 streams from the example above:
@@ -55,7 +56,7 @@ const streamB = getRepeaterStream('B', 15); // fake helper function that returns
 const streamC = getRepeaterStream('C', 10); // fake helper function that returns a ReadableStream
 ```
 
-Now, instantiate a stream collator instance and register the streams with it:
+Next, instantiate a stream collator instance and register the streams with it:
 
 ```javascript
 const collator = new StreamCollator();

libraries/stream-collator/src/index.ts

@@ -1,6 +1,18 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+/**
+ * This library enables a tool to display live console output from multiple asynchronous processes,
+ * while ensuring that their output does not get jumbled together.
+ *
+ * @remarks
+ *
+ * For more info, please see the package {@link https://www.npmjs.com/package/@microsoft/stream-collator
+ * | README}.
+ *
+ * @packageDocumentation
+ */
+
 export {
   Interleaver,
   ITaskWriter

libraries/ts-command-line/README.md

@@ -189,7 +189,8 @@ You can also mix the two models.  For example, we could augment the `WidgetComma
 
 ### Further reading
 
-The [API reference](https://microsoft.github.io/web-build-tools/api/) has complete documentation for the library.
+The [API reference](https://rushstack.io/pages/api/ts-command-line/) has
+complete documentation for the library.
 
 Here are some real world GitHub projects that illustrate different use cases for **ts-command-line**: