You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat(docs): enrich type information for docs-json Output Target (#4212)
This enriches the type information supplied in the `docs-json` output
target in order to make it easier to deliver a rich documentation
experience for a Stencil project.
This involves three significant changes.
Firstly, the information which the `docs-json` OT gathers about the
properties which comprise the API of a Stencil component is expanded to
include more information about the types used in the declaration of the
property. In particular, this means that if you have, say, a `@Method`
on a component whose signature involves several types imported from
other modules the JSON blob for that method will now include more
detailed information about all the types used in that declaration.
This information is stored under the `complexType` key for each field on
a component. This `complexType` object includes a `references` object
which now includes a new, globally-unique ID for each type in a Stencil
project which looks like:
```ts
const typeID = `${pathToTypeHomeModule}::${typeName}`;
```
where `pathToTypeHomeModule` is the path to the type's "home" module,
i.e. where it was originally declared, and `typeName` is the _original_
name it is declared under in that module. This if you had a type like
the following:
```ts src/shared-interfaces.ts
export interface SharedInterface {
property: "value";
}
```
the `SharedInterface` type would have the following ID:
```ts
"src/shared-interfaces.ts::SharedInterface"
```
This unique identifier allows cross-references to be made between the
_usage sites_ of a type (as documented in the JSON blob for, say, a
`@Method` or `@Prop`) and canonical information about that type.
The second major addition is the creation of a new canonical reference
point for all exported types used within a Stencil project. This
reference is called the _type library_ and it is included in the
`docs-json` output target under the `"typeLibrary"` key. It's an object
which maps the unique type IDs described above to an object containing
information about those types, including their original declaration
rendered as a string, the path to their home module, and documentation,
if present
> Note that global types, types imported from `node_modules`, and
types marked as private with the `@private` JSDoc tag are not included
in the type library, even if they are used in the declaration of a
property decorated with a Stencil decorator.
The combination of globally-unique type IDs and the type library will
allow Stencil component authors to create richer documentation
experiences where the usage sites of a widely imported type can easily
be linked to a canonical reference point for that type.
The third addition is a new configuration option for the `docs-json`
output target called `supplementalPublicTypes`. This option takes a
filepath which points to a file exporting types and interfaces which
should be included in the type library regardless of whether they are
used in the API of any component included in the Stencil project.
The motivation for `supplementalPublicTypes` is to facilitate the
documentation of types and interfaces which are important for a given
project but which may not be included in the type library because
they're not used by a `@Prop()`, `@Event()`, or another Stencil
decorator.
0 commit comments