Skip to content

Commit

Permalink
Add api-extractor generated docs for di and context export paths (#6979)
Browse files Browse the repository at this point in the history
# Pull Request

## 📖 Description

This change points the `api-extractor` to the `di` and `context` export paths and adds this generated documentation to the documentation site.

### 🎫 Issues

Resolves #6090

## 👩‍💻 Reviewer Notes

This is was a little fiddly as the `api-extractor` does not export export paths, additionally the way the `api-documentor` works assumes a single entry path. This is why if any additions need to be made to expose more export paths, we will need to edit 3 different files to get the documentation to show up on the documentation website.

## ✅ Checklist

### General

<!--- Review the list and put an x in the boxes that apply. -->

- [x] I have included a change request file using `$ yarn change`
- [ ] I have added tests for my changes.
- [x] I have tested my changes.
- [x] I have updated the project documentation to reflect my changes.
- [x] I have read the [CONTRIBUTING](https://github.com/microsoft/fast/blob/master/CONTRIBUTING.md) documentation and followed the [standards](https://github.com/microsoft/fast/blob/master/CODE_OF_CONDUCT.md#our-standards) for this project.
  • Loading branch information
janechu authored Aug 1, 2024
1 parent 4f166dc commit 97bf709
Show file tree
Hide file tree
Showing 9 changed files with 574 additions and 40 deletions.
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"type": "none",
"comment": "Add api-extractor generated docs for di and context export paths",
"packageName": "@microsoft/fast-element",
"email": "[email protected]",
"dependentChangeType": "none"
}
14 changes: 14 additions & 0 deletions packages/web-components/fast-element/api-extractor.context.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
"extends": "../../../api-extractor.json",
"mainEntryPointFilePath": "./dist/dts/context.d.ts",
"apiReport": {
"enabled": true,
"reportFolder": "<projectFolder>/docs/context",
"reportFileName": "api-report.md"
},
"docModel": {
"enabled": true,
"apiJsonFilePath": "<projectFolder>/dist/context/context.api.json"
}
}
14 changes: 14 additions & 0 deletions packages/web-components/fast-element/api-extractor.di.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
"extends": "../../../api-extractor.json",
"mainEntryPointFilePath": "./dist/dts/di/di.d.ts",
"apiReport": {
"enabled": true,
"reportFolder": "<projectFolder>/docs/di",
"reportFileName": "api-report.md"
},
"docModel": {
"enabled": true,
"apiJsonFilePath": "<projectFolder>/dist/di/di.api.json"
}
}
69 changes: 69 additions & 0 deletions packages/web-components/fast-element/docs/context/api-report.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
## API Report File for "@microsoft/fast-element"

> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
```ts

// @public
export type Context<T> = {
readonly name: string;
readonly initialValue?: T;
};

// @public
export const Context: Readonly<{
eventType: "context-request";
for<T = unknown>(name: string): FASTContext<T>;
create<T_1 = unknown>(name: string, initialValue?: T_1 | undefined): FASTContext<T_1>;
setDefaultRequestStrategy(strategy: FASTContextRequestStrategy): void;
get<T_2 extends UnknownContext>(target: EventTarget, context: T_2): ContextType<T_2>;
request<T_3 extends UnknownContext>(target: EventTarget, context: T_3, callback: ContextCallback<ContextType<T_3>>, multiple?: boolean): void;
dispatch<T_4 extends UnknownContext>(target: EventTarget, context: T_4, callback: ContextCallback<ContextType<T_4>>, multiple?: boolean): void;
provide<T_5 extends UnknownContext>(target: EventTarget, context: T_5, value: ContextType<T_5>): void;
handle<T_6 extends UnknownContext>(target: EventTarget, callback: (event: ContextEvent<T_6>) => void, context?: T_6 | undefined): void;
defineProperty<T_7 extends UnknownContext>(target: Constructable<EventTarget> | EventTarget, propertyName: string, context: T_7): void;
}>;

// @public
export type ContextCallback<ValueType> = (value: ValueType, dispose?: () => void) => void;

// Warning: (ae-forgotten-export) The symbol "ParameterDecorator" needs to be exported by the entry point context.d.ts
//
// @public
export type ContextDecorator<T = any> = Readonly<Context<T>> & PropertyDecorator & ParameterDecorator_2;

// @public
export class ContextEvent<T extends UnknownContext> extends Event {
constructor(context: T, callback: ContextCallback<ContextType<T>>, multiple?: boolean | undefined);
// (undocumented)
readonly callback: ContextCallback<ContextType<T>>;
// (undocumented)
readonly context: T;
// (undocumented)
readonly multiple?: boolean | undefined;
}

// @public
export type ContextType<T extends UnknownContext> = T extends Context<infer Y> ? Y : never;

// @public
export type FASTContext<T> = ContextDecorator<T> & {
get(target: EventTarget): T;
provide(target: EventTarget, value: T): void;
request(target: EventTarget, callback: ContextCallback<T>, multiple?: boolean): void;
handle(target: EventTarget, callback: (event: ContextEvent<FASTContext<T>>) => void): void;
};

// @public
export type FASTContextRequestStrategy = <T extends UnknownContext>(target: EventTarget, context: T, callback: ContextCallback<ContextType<T>>, multiple: any) => void;

// @public
export type UnknownContext = Context<unknown>;

// Warnings were encountered during analysis:
//
// dist/dts/context.d.ts:127:5 - (ae-forgotten-export) The symbol "Constructable" needs to be exported by the entry point context.d.ts

// (No @packageDocumentation comment for this package)

```
Loading

0 comments on commit 97bf709

Please sign in to comment.