webcomponents / webcomponents/custom-elements-manifest

Add support for including canonical URLs for References

Open
#115 0 comments 0 reactions 0 assignees View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.