webcomponents / webcomponents/custom-elements-manifest
Add support for including canonical URLs for References
- Dominant language
- TypeScript
- Stars
- 502
- Forks
- 27
- PR merge metrics
- No merged PRs in 30d
Description
When generating documentation from a manifest that may include references to 3rd-party packages, it may be useful for a 3rd-party package to describe canonical URLs to documentation for specific `Reference`.
For example, take the following example:
```ts
// my-foo.ts
import {FooElement} from 'foo';
export class MyFoo extends FooElement { ... }
```
Which would create the following CEM snippet:
```json
{
"modules": [
{
"kind": "javascript-module",
"path": "my-foo.js",
"declarations": [
{
"kind": "class",
"name": "MyFoo",
"superclass": { "name": "MyFoo", "package": "foo" },
}
]
}
]
}
```
An API documentation generator might like to show documentation such as this:
```md
## Classes
### MyFoo
Extends: [`FooElement`](https://foo-library.com/api/FooElement.html) from `foo`
#### Fields
...
#### Methods
...
```
Where the link on `FooElement` links to the canonical documentation for `FooElement`. While an API documentation generator could retrieve the CEM for `foo` and generate / link to that documentation locally, as an option it would be useful if a CEM could say, _"the canonical documentation URL for `FooElement` is at `https://foo-library.com/api/FooElement.html`"_.
## Proposed schema addition:
```md
/**
* A reference to the canonical documentation of a declaration.
*/
export interface DocumentationReference {
/**
* An absolute URL to canonical API documentation.
*/
href: string;
}
```
and add
```
documentation?: DocumentationReference
```
to all declaration types.
So in the above example, the CEM for `foo` might look like:
```json
{
"modules": [
{
"kind": "javascript-module",
"path": "foo-element.js",
"declarations": [
{
"kind": "class",
"name": "FooElement",
"documentation": {"href": "https://foo-library.com/api/FooElement.html"},
}
]
}
]
}
```
Additionally, in order to make a pre-flattened schema (where all transitive documentation links are inlined into a manifest, e.g. via pre-processing, to eliminate round-trips to fetch CEM's for referenced dependencies), `DocumentationReference` would be added as an optional property to `Reference` as well. This is similar in concept to the `inheritedFrom` option for class members.
As such, a valid `my-foo` CEM could include the canonical documentation link for the superclass:
```json
{
"modules": [
{
"kind": "javascript-module",
"path": "my-foo.js",
"declarations": [
{
"kind": "class",
"name": "MyFoo",
"superclass": {
"name": "MyFoo",
"package": "foo",
"documentation": {"href": "https://foo-library.com/api/FooElement.html"}
},
...
}
]
}
]
}
```
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.