Skip to content

Commit f059d60

Browse files
octogonzoctogonz
committed
Tune up package documentation, add links to the new API reference website
1 parent a8d3f27 commit f059d60

19 files changed

Lines changed: 107 additions & 73 deletions

File tree

‎apps/api-documenter/README.md‎

Lines changed: 6 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,11 @@
22

33
This tool can be used to generate an online API reference manual for your TypeScript library.
44
It reads the *.api.json data files produced by [API Extractor](https://api-extractor.com/),
5-
and then generates web pages using the [Markdown](https://en.wikipedia.org/wiki/Markdown)
6-
file format.
5+
and then generates files in [Markdown](https://en.wikipedia.org/wiki/Markdown) or
6+
[DocFX](https://dotnet.github.io/docfx/) format.
77

8-
The **api-documenter** tool is part of Microsoft's production documentation pipeline.
9-
It is provided as a code sample to illustrate how to load and process the
10-
API JSON file format. If your requirements are simple, you can use this tool directly.
11-
For more advanced scenarios, developers are encouraged to fork the project and modify
12-
the source code. The implementation is intentionally kept simple and easy
13-
to understand. This is possible because most of processing is already performed upstream
14-
by API Extractor.
8+
For usage information, see the
9+
[Generating Docs](https://api-extractor.com/pages/setup/generating_docs/) article from the API Extractor
10+
documentation.
1511

16-
For more information, see the
17-
[Generating Docs](https://api-extractor.com/pages/setup/generating_docs/) article from the API Extractor documentation.
12+
API documentation for this package: https://rushstack.io/pages/api/api-documenter/

‎apps/api-documenter/src/index.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,14 @@
11
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
22
// See LICENSE in the project root for license information.
33

4+
/**
5+
* API Documenter generates an API reference website from the .api.json files created by API Extractor.
6+
* The `@microsoft/api-documenter` package provides the command-line tool. It also exposes a developer API that you
7+
* can use to create plugins that customize how API Documenter generates documentation.
8+
*
9+
* @packageDocumentation
10+
*/
11+
412
export {
513
IFeatureDefinition,
614
IApiDocumenterPluginManifest

‎apps/api-extractor-model/README.md‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
11
# @microsoft/api-extractor-model
22

3-
This library is used with the [@microsoft/api-extractor](https://www.npmjs.com/package/@microsoft/api-extractor).
4-
For documentation and other information about the API Extractor tool, please visit the
5-
[web site](https://api-extractor.com/).
3+
Use this library to read and write *.api.json files as defined by the [API Extractor](https://api-extractor.com/) tool.
4+
These files are used to generate a documentation website for your TypeScript package. The files store the
5+
API signatures and doc comments that were extracted from your package.
66

7-
The **@microsoft/api-extractor-model** library is used to read and write the *.api.json data file format,
8-
which stores information about the exported API signatures for a TypeScript project.
7+
API documentation for this package: https://rushstack.io/pages/api/api-extractor-model/
98

109
## Example Usage
1110

@@ -56,5 +55,5 @@ to extend more than one base class). The "mixin" is a TypeScript merged declara
5655
the function that generates a subclass, an interface that describes the members of the subclass, and
5756
a namespace containing static members of the class.
5857

59-
> For a complete example that shows how to uset these APIs to generate an API reference web site,
58+
> For a complete project that uses these APIs to generate an API reference web site,
6059
> see the [@microsoft/api-documenter](https://www.npmjs.com/package/@microsoft/api-documenter) source code.

‎apps/api-extractor-model/src/index.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,10 @@
22
// See LICENSE in the project root for license information.
33

44
/**
5-
* API Extractor helps you build better TypeScript library packages.
6-
* It helps with validation, documentation, and reviewing of the exported API
7-
* for a TypeScript library.
5+
* Use this library to read and write *.api.json files as defined by the
6+
* {@link https://api-extractor.com/ | API Extractor} tool. These files are used to generate a documentation
7+
* website for your TypeScript package. The files store the API signatures and doc comments that were extracted
8+
* from your package.
89
*
910
* @packageDocumentation
1011
*/

‎apps/api-extractor/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,3 +40,5 @@ Best of all, **API Extractor** is free and open source. Join the community and
4040
# Getting Started
4141

4242
For more details and support resources, please visit: https://api-extractor.com/
43+
44+
API documentation for this package: https://rushstack.io/pages/api/api-extractor/

‎apps/api-extractor/src/index.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
// See LICENSE in the project root for license information.
33

44
/**
5-
* API Extractor helps you build better TypeScript library packages.
6-
* It helps with validation, documentation, and reviewing of the exported API
7-
* for a TypeScript library.
5+
* API Extractor helps with validation, documentation, and reviewing of the exported API for a TypeScript library.
6+
* The `@microsoft/api-extractor` package provides the command-line tool. It also exposes a developer API that you
7+
* can use to invoke API Extractor programmatically.
88
*
99
* @packageDocumentation
1010
*/

‎apps/rush-lib/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,5 @@ might interfere with the globally installed Rush).
1212

1313
The **@microsoft/rush** version number is always exactly equal
1414
to the **@microsoft/rush-lib** version number that it depends on.
15+
16+
API documentation for this package: https://rushstack.io/pages/api/rush-lib/

‎apps/rush-lib/src/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
// See LICENSE in the project root for license information.
33

44
/**
5-
* A library for writing scripts that interact with the Rush tool.
5+
* A library for writing scripts that interact with the {@link https://rushjs.io/ | Rush} tool.
66
* @packageDocumentation
77
*/
88

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

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,4 @@ export class PluginFeatureInitialization {
8282
}
8383

8484

85-
// (No @packageDocumentation comment for this package)
86-
8785
```

‎common/reviews/api/package-deps-hash.api.md‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,13 @@
77
// @public
88
export function getPackageDeps(packagePath?: string, excludedPaths?: string[]): IPackageDeps;
99

10-
// @public (undocumented)
10+
// @public
1111
export interface IPackageDeps {
12-
// (undocumented)
12+
arguments?: string;
1313
files: {
1414
[key: string]: string;
1515
};
1616
}
1717

1818

19-
// (No @packageDocumentation comment for this package)
20-
2119
```

0 commit comments

Comments
 (0)