Skip to content

Commit 3f3bc8c

Browse files
octogonzoctogonz
committed
Add documentation, rename PluginInitialization --> PluginFeatureInitialization
1 parent b625b95 commit 3f3bc8c

File tree

6 files changed

+106
-42
lines changed

6 files changed

+106
-42
lines changed

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
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-
export { MarkdownDocumenterFeature, PluginInitialization } from './plugin/MarkdownDocumenterFeature';
4+
export { MarkdownDocumenterFeature } from './plugin/MarkdownDocumenterFeature';
5+
export { PluginFeature, PluginFeatureInitialization } from './plugin/PluginFeature';
56
export {
67
IFeatureDefinition,
78
IApiDocumenterPluginManifest

‎apps/api-documenter/src/plugin/IApiDocumenterPluginManifest.ts‎

Lines changed: 42 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
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-
import {
5-
MarkdownDocumenterFeature,
6-
PluginInitialization
7-
} from './MarkdownDocumenterFeature';
4+
import { MarkdownDocumenterFeature } from './MarkdownDocumenterFeature';
5+
import { PluginFeatureInitialization } from './PluginFeature';
86

7+
/**
8+
* Defines a "feature" that is provided by an API Documenter plugin. A feature is a user-defined module
9+
* that customizes the behavior of API Documenter.
10+
*/
911
export interface IFeatureDefinition {
1012
/**
1113
* The name of this feature, as it will appear in the config file.
@@ -16,21 +18,55 @@ export interface IFeatureDefinition {
1618
featureName: string;
1719

1820
/**
19-
* The name of the feature base class.
21+
* Determines the kind of feature. The specified value is the name of the base class that `subclass` inherits from.
22+
*
23+
* @remarks
24+
* For now, `MarkdownDocumenterFeature` is the only supported value.
2025
*/
2126
kind: 'MarkdownDocumenterFeature';
2227

2328
/**
2429
* Your subclass that extends from the base class.
2530
*/
26-
subclass: { new(initialization: PluginInitialization): MarkdownDocumenterFeature };
31+
subclass: { new(initialization: PluginFeatureInitialization): MarkdownDocumenterFeature };
2732
}
2833

2934
/**
35+
* The manifest for an API Documenter plugin.
36+
*
37+
* @remarks
38+
* An API documenter plugin is an NPM package. By convention, the NPM package name should have the prefix
39+
* `doc-plugin-`. Its main entry point should export an object named `apiDocumenterPluginManifest` which implements
40+
* the `IApiDocumenterPluginManifest` interface.
41+
*
42+
* For example:
43+
* ```ts
44+
* class MyMarkdownDocumenter extends MarkdownDocumenterFeature {
45+
* public onInitialized(): void {
46+
* console.log('MyMarkdownDocumenter: onInitialized()');
47+
* }
48+
* }
3049
*
50+
* export const apiDocumenterPluginManifest: IApiDocumenterPluginManifest = {
51+
* manifestVersion: 1000,
52+
* features: [
53+
* {
54+
* featureName: 'my-markdown-documenter',
55+
* kind: 'MarkdownDocumenterFeature',
56+
* subclass: MyMarkdownDocumenter
57+
* }
58+
* ]
59+
* };
60+
* ```
3161
*/
3262
export interface IApiDocumenterPluginManifest {
63+
/**
64+
* The manifest version number. For now, this must always be `1000`.
65+
*/
3366
manifestVersion: 1000;
3467

68+
/**
69+
* The list of features provided by this plugin.
70+
*/
3571
features: IFeatureDefinition[];
3672
}

‎apps/api-documenter/src/plugin/MarkdownDocumenterFeature.ts‎

Lines changed: 5 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,13 @@
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-
* @public
6-
*/
7-
export class PluginInitialization {
8-
}
4+
import { PluginFeature } from './PluginFeature';
95

106
/**
7+
* Inherit from this base class to implement an API Documenter plugin feature that customizes
8+
* the generation of markdown output.
9+
*
1110
* @public
1211
*/
13-
export class MarkdownDocumenterFeature {
14-
/**
15-
* The subclass should pass the `initialization` through to the base class.
16-
* Do not put custom initialization code in the constructor. Insteadm perform your initialization in the
17-
* `onInitialized()` event function.
18-
* @internal
19-
*/
20-
public constructor(initialization: PluginInitialization) {
21-
// reserved for future expansion
22-
}
23-
24-
/**
25-
* This event function is called after the feature is initialized, but before any processing occurs.
26-
* @virtual
27-
*/
28-
public onInitialized(): void {
29-
// (implemented by child class)
30-
}
12+
export class MarkdownDocumenterFeature extends PluginFeature {
3113
}

‎apps/api-documenter/src/plugin/PluginContext.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import * as resolve from 'resolve';
77
import { IConfigPlugin } from '../documenters/IConfigFile';
88
import { IApiDocumenterPluginManifest, IFeatureDefinition } from './IApiDocumenterPluginManifest';
99
import { MarkdownDocumenterFeature } from './MarkdownDocumenterFeature';
10-
import { PluginInitialization } from './MarkdownDocumenterFeature';
10+
import { PluginFeatureInitialization } from './PluginFeature';
1111

1212
interface ILoadedPlugin {
1313
packageName: string;
@@ -69,7 +69,7 @@ export class PluginContext {
6969
throw new Error('A MarkdownDocumenterFeature is already loaded');
7070
}
7171

72-
const initialization: PluginInitialization = new PluginInitialization();
72+
const initialization: PluginFeatureInitialization = new PluginFeatureInitialization();
7373
let markdownDocumenterFeature: MarkdownDocumenterFeature | undefined = undefined;
7474
try {
7575
markdownDocumenterFeature = new featureDefinition.subclass(initialization);

‎apps/api-documenter/src/plugin/PluginFeature.ts‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
2+
// See LICENSE in the project root for license information.
3+
4+
/**
5+
* This is an internal part of the plugin infrastructure.
6+
*
7+
* @remarks
8+
* This object is the constructor parameter for API Documenter plugin features.
9+
*
10+
* @public
11+
*/
12+
export class PluginFeatureInitialization {
13+
/** @internal */
14+
public constructor() {
15+
// reserved for future use
16+
}
17+
}
18+
19+
/**
20+
* The abstract base class for all API Documenter plugin features.
21+
* @public
22+
*/
23+
export abstract class PluginFeature {
24+
/**
25+
* The subclass should pass the `initialization` through to the base class.
26+
* Do not put custom initialization code in the constructor. Insteadm perform your initialization in the
27+
* `onInitialized()` event function.
28+
* @internal
29+
*/
30+
public constructor(initialization: PluginFeatureInitialization) {
31+
// reserved for future expansion
32+
}
33+
34+
/**
35+
* This event function is called after the feature is initialized, but before any processing occurs.
36+
* @virtual
37+
*/
38+
public onInitialized(): void {
39+
// (implemented by child class)
40+
}
41+
}

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

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,33 +4,37 @@
44
55
```ts
66

7-
// @public (undocumented)
7+
// @public
88
export interface IApiDocumenterPluginManifest {
9-
// (undocumented)
109
features: IFeatureDefinition[];
11-
// (undocumented)
1210
manifestVersion: 1000;
1311
}
1412

15-
// @public (undocumented)
13+
// @public
1614
export interface IFeatureDefinition {
1715
featureName: string;
1816
kind: 'MarkdownDocumenterFeature';
1917
subclass: {
20-
new (initialization: PluginInitialization): MarkdownDocumenterFeature;
18+
new (initialization: PluginFeatureInitialization): MarkdownDocumenterFeature;
2119
};
2220
}
2321

24-
// @public (undocumented)
25-
export class MarkdownDocumenterFeature {
22+
// @public
23+
export class MarkdownDocumenterFeature extends PluginFeature {
24+
}
25+
26+
// @public
27+
export abstract class PluginFeature {
2628
// @internal
27-
constructor(initialization: PluginInitialization);
29+
constructor(initialization: PluginFeatureInitialization);
2830
// @virtual
2931
onInitialized(): void;
3032
}
3133

32-
// @public (undocumented)
33-
export class PluginInitialization {
34+
// @public
35+
export class PluginFeatureInitialization {
36+
// @internal
37+
constructor();
3438
}
3539

3640

0 commit comments

Comments
 (0)