Define MarkdownDocumenterFeature.onBeforeWritePage() event

octogonz · octogonz · commit f38f8258b07b · 2019-09-04T23:42:30.000-07:00
diff --git a/apps/api-documenter/src/index.ts b/apps/api-documenter/src/index.ts
@@ -1,9 +1,17 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
-export { MarkdownDocumenterFeature } from './plugin/MarkdownDocumenterFeature';
-export { PluginFeature, PluginFeatureInitialization } from './plugin/PluginFeature';
 export {
   IFeatureDefinition,
   IApiDocumenterPluginManifest
 } from './plugin/IApiDocumenterPluginManifest';
+export {
+  MarkdownDocumenterFeatureContext,
+  IMarkdownDocumenterFeatureOnBeforeWritePage,
+  MarkdownDocumenterFeature
+} from './plugin/MarkdownDocumenterFeature';
+export {
+  PluginFeature,
+  PluginFeatureContext,
+  PluginFeatureInitialization
+} from './plugin/PluginFeature';
diff --git a/apps/api-documenter/src/plugin/MarkdownDocumenterFeature.ts b/apps/api-documenter/src/plugin/MarkdownDocumenterFeature.ts
@@ -2,6 +2,37 @@
 // See LICENSE in the project root for license information.
 
 import { PluginFeature } from './PluginFeature';
+import { ApiItem } from '@microsoft/api-extractor-model';
+
+/**
+ * Context object for {@link MarkdownDocumenterFeature}.
+ *
+ * @public
+ */
+export class MarkdownDocumenterFeatureContext {
+
+}
+
+/**
+ * Event arguments for MarkdownDocumenterFeature.onBeforeWritePage()
+ * @public
+ */
+export interface IMarkdownDocumenterFeatureOnBeforeWritePage {
+  /**
+   * The API item corresponding to this page.
+   */
+  apiItem: ApiItem;
+
+  /**
+   * The page content.  The onBeforeWritePage() handler can reassign this string to customize the page appearance.
+   */
+  pageContent: string;
+
+  /**
+   * The filename where the output will be written.
+   */
+  outputFilename: string;
+}
 
 /**
  * Inherit from this base class to implement an API Documenter plugin feature that customizes
@@ -10,4 +41,13 @@ import { PluginFeature } from './PluginFeature';
  * @public
  */
 export class MarkdownDocumenterFeature extends PluginFeature {
+  public context: MarkdownDocumenterFeatureContext;
+
+  /**
+   * This event function is called before writing a page.
+   * @virtual
+   */
+  public onBeforeWritePage(eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePage): void {
+    // (implemented by child class)
+  }
 }
diff --git a/apps/api-documenter/src/plugin/PluginFeature.ts b/apps/api-documenter/src/plugin/PluginFeature.ts
@@ -14,13 +14,26 @@ export class PluginFeatureInitialization {
   public constructor() {
     // reserved for future use
   }
+
+  /** @internal */
+  public _context: PluginFeatureContext;
+}
+
+/**
+ * Context object for {@link PluginFeature}.
+ *
+ * @public
+ */
+export class PluginFeatureContext {
 }
 
 /**
  * The abstract base class for all API Documenter plugin features.
  * @public
  */
 export abstract class PluginFeature {
+  public context: PluginFeatureContext;
+
   /**
    * The subclass should pass the `initialization` through to the base class.
    * Do not put custom initialization code in the constructor.  Insteadm perform your initialization in the
@@ -29,6 +42,7 @@ export abstract class PluginFeature {
    */
   public constructor(initialization: PluginFeatureInitialization) {
     // reserved for future expansion
+    this.context = initialization._context;
   }
 
   /**
diff --git a/apps/api-documenter/src/plugin/PluginLoader.ts b/apps/api-documenter/src/plugin/PluginLoader.ts
@@ -6,7 +6,7 @@ import * as resolve from 'resolve';
 
 import { IConfigPlugin } from '../documenters/IConfigFile';
 import { IApiDocumenterPluginManifest, IFeatureDefinition } from './IApiDocumenterPluginManifest';
-import { MarkdownDocumenterFeature } from './MarkdownDocumenterFeature';
+import { MarkdownDocumenterFeature, MarkdownDocumenterFeatureContext } from './MarkdownDocumenterFeature';
 import { PluginFeatureInitialization } from './PluginFeature';
 
 interface ILoadedPlugin {
@@ -69,7 +69,11 @@ export class PluginLoader {
               throw new Error('A MarkdownDocumenterFeature is already loaded');
             }
 
+            const context: MarkdownDocumenterFeatureContext = new MarkdownDocumenterFeatureContext();
+
             const initialization: PluginFeatureInitialization  = new PluginFeatureInitialization();
+            initialization._context = context;
+
             let markdownDocumenterFeature: MarkdownDocumenterFeature | undefined = undefined;
             try {
               markdownDocumenterFeature = new featureDefinition.subclass(initialization);
diff --git a/apps/api-documenter/tslint.json b/apps/api-documenter/tslint.json
@@ -1,3 +1,6 @@
 {
-  "extends": "@microsoft/rush-stack-compiler-3.4/includes/tslint.json"
+  "extends": "@microsoft/rush-stack-compiler-3.4/includes/tslint.json",
+  "rules": {
+    "member-ordering": false
+  }
 }
diff --git a/common/reviews/api/api-documenter.api.md b/common/reviews/api/api-documenter.api.md
@@ -4,6 +4,8 @@
 
 ```ts
 
+import { ApiItem } from '@microsoft/api-extractor-model';
+
 // @public
 export interface IApiDocumenterPluginManifest {
     features: IFeatureDefinition[];
@@ -19,22 +21,45 @@ export interface IFeatureDefinition {
     };
 }
 
+// @public
+export interface IMarkdownDocumenterFeatureOnBeforeWritePage {
+    apiItem: ApiItem;
+    outputFilename: string;
+    pageContent: string;
+}
+
 // @public
 export class MarkdownDocumenterFeature extends PluginFeature {
+    // (undocumented)
+    context: MarkdownDocumenterFeatureContext;
+    // @virtual
+    onBeforeWritePage(eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePage): void;
+}
+
+// @public
+export class MarkdownDocumenterFeatureContext {
 }
 
 // @public
 export abstract class PluginFeature {
     // @internal
     constructor(initialization: PluginFeatureInitialization);
+    // (undocumented)
+    context: PluginFeatureContext;
     // @virtual
     onInitialized(): void;
 }
 
+// @public
+export class PluginFeatureContext {
+}
+
 // @public
 export class PluginFeatureInitialization {
     // @internal
     constructor();
+    // @internal (undocumented)
+    _context: PluginFeatureContext;
 }
 
 

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,6 @@`
`1`	`1`	`{`
`2`		`- "extends": "@microsoft/rush-stack-compiler-3.4/includes/tslint.json"`
	`2`	`+ "extends": "@microsoft/rush-stack-compiler-3.4/includes/tslint.json",`
	`3`	`+ "rules": {`
	`4`	`+ "member-ordering": false`
	`5`	`+ }`
`3`	`6`	`}`