Api extractor for utilities #6406
Conversation
…i-extractor-test.json
…c-react into api-extractor
packages/utilities/src/styled.tsx
Outdated
| @@ -15,7 +15,7 @@ export interface ICustomizableProps { | |||
|
|
|||
| /** | |||
| * List of fields which can be customized. | |||
| * @default [ 'theme', 'styles' ] | |||
| * Default value: <pre>[ 'theme', 'styles' ]</pre> | |||
There was a problem hiding this comment.
Why do we change these from jsdoc commands?
There was a problem hiding this comment.
Why do we change these from jsdoc commands?
The <pre> HTML tag was just a temporary workaround because API Extractor does not yet support Markdown-style backticks. (That will be solved by the upcoming PR #827.)
Generally API Extractor is aligning with TSDoc, which has some differences from JSDoc. You can read about it here:
https://github.com/Microsoft/tsdoc
BTW there is an issue #27 proposing to support the @default tag in TSDoc. It hasn't been integrated yet because the spec for @default is still a little vague. Feel free to contribute to that issue if you think it's an important feature.
|
This work item will wait until API Extractor @default tag support is resolved. |
…c-react into api-extractor
| @@ -86,8 +86,8 @@ export function getParent(child: HTMLElement, allowVirtualParents: boolean = tru | |||
| * Gets the elements which are child elements of the given element. | |||
| * If `allowVirtualChildren` is `true`, this method enumerates virtual child elements | |||
| * after the original children. | |||
| * @param parent | |||
| * @param allowVirtualChildren | |||
| * @param parent - The element to get the children of. | |||
There was a problem hiding this comment.
Is the - between the parameter and the rest of the line something introduced by API Extractor? The jsdoc standard doesn't require it and in fact Typescript doesn't require it. Including it will result in the - superfluously showing up in intellisense
There was a problem hiding this comment.
@cliffkoh Yes, and TSDoc will require the hyphen in "strict" mode. Omitting the hyphen would be ambiguous and error-prone, e.g. considering the other optional type annotations that JSDoc permits (which are not needed in TypeScript, but commonly occur nonetheless in TypeScript code bases).
I believe the IntelliSense you're referring to is coming from the VS Code plugin, not the TypeScript compiler itself. If you strongly object to the hyphen, you could open a TSDoc issue to discuss it. Otherwise I'd suggest to open a GitHub issue for VS Code; their doc comment analysis already has a number of other known issues -- this was part of the motivation for the compiler group getting involved with TSDoc.
packages/utilities/src/styled.tsx
Outdated
| @@ -26,13 +26,13 @@ const DefaultFields = ['theme', 'styles']; | |||
| * The styled HOC wrapper allows you to create a functional wrapper around a given component which will resolve | |||
| * getStyles functional props, and mix customized props passed in using concatStyleSets. | |||
| * | |||
| * @example | |||
| * ```tsx | |||
| * Example: | |||
There was a problem hiding this comment.
This is also regressive, but isn't as serious as the @defaultvalue. Would be good to understand where support for @example is on API Extractor's roadmap.
There was a problem hiding this comment.
@cliffkoh The @example tag is already part of TSDoc and will be accepted in API Extractor 6. The syntax is discussed in microsoft/tsdoc#20
If you have suggestions/questions, please add them to that issue.
|
HURRAY!! :-P |
|
🎉 Handy Links: |
Pull request checklist
$ npm run changeDescription of changes
Enable the api-extractor task for the utilities package. Future PRs will enable api-extractor for other packages, add api-extractor to the CI build, and add code owners to *.api.ts files.
Focus areas to test
(optional)
Microsoft Reviewers: Open in CodeFlow