Feature Request: `Documented` Utility Type
See original GitHub issueSearch Terms
Docs, documentation, re-key, utility, type, extract, literal, update, tsdoc, comment, source, text
Suggestion
I’d love to see documentation as a first-class citizen of the type system. My suggestion is a new utility type Documented
, which allows users to document and unwrap documentation at the type-level.
The type could look as follows: Documented<V, D extends string> = V
.
This:
type X = {
a: Documented<string, "Some documentation for `a`">;
};
… would be equivalent to this:
type X = {
/**
* Some documentation for `a`
*/
a: string;
};
While it would be preferable for consistency to specify the documentation attached to the key (as this is how mapped types transfer documentation), index signature and other contextual restrictions apply. Aka., this is no good:
type X = {
[Documented<"a", "Some documentation for `a`">]: string;
}
Additionally, accessing the symbol of the literal of a specific key can be arduous (Extract<keyof ..., ...
>). Whereas accessing the symbol of the field is simple (X["a"]
).
ALSO: apologies if I’m butchering the terminology.
Use Cases
This utility type would enable users to extract documentation as string literal types, which they could then further manipulate and use elsewhere. They could build up higher-order generic types to assist with and type-check the documentation process.
Examples
type X = {
/**
* Some documentation for `a`
*/
a: string;
};
type XaDocs = X["a"] extends Documented<any, infer D> ? D : undefined;
declare const xaDocs: XaDocs; // "Some documentation for `a`"
// update (prefix) the string literal type of the documentation
type XaDocsUpdated = XaDocs extends string ? `USE WITH CAUTION: ${XaDocs}` : undefined;
// utilize the `Documented` utility to attach the new documentation
type XUpdated1 = {
a: Documented<string, XaDocsUpdated>;
};
// perhaps within a mapped type
type XUpdated2 = {
[K in keyof X]: K extends "a" ? Documented<X[K], XaDocsUpdated> : X[K];
};
In either of the cases above, a
will be documented as “USE WITH CAUTION: Some documentation for a
”.
The real power of this utility is not in direct usage as demoed above, but rather in higher-order utilities. For instance, you could imagine a utility library that lets users specify flags that correspond to expected documentation.
import {EnsureDocumentationExists} from "some-doc-utility-lib";
import {HasDescriptionAndExampleDocs, HasDescriptionDocs} from "./my-own-potentially-poorly-documented-types";
export type A = EnsureDocumentationExists<HasDescriptionAndExampleDocs, {description: true; example: true}>;
export type B = EnsureDocumentationExists<HasDescriptionDocs, {description: true; example: true}>; // type-error
export type C = EnsureDocumentationExists<HasDescriptionDocs, {description: true}>;
Checklist
My suggestion meets these guidelines:
- This wouldn’t be a breaking change in existing TypeScript/JavaScript code
- This wouldn’t change the runtime behavior of existing JavaScript code
- This could be implemented without emitting different JS based on the types of the expressions
- This isn’t a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
- This feature would agree with the rest of TypeScript’s Design Goals.
Issue Analytics
- State:
- Created 3 years ago
- Reactions:28
- Comments:18 (9 by maintainers)
So, after digging around for a while in typescript’s source, I have started to figure out how the documentation stuff gets handled.
AFAICT, when it is retrieving the documentation, it:
getQuickInfoAtPosition
insrc/services/services.ts
Symbol
and notSymbolObject
, but I didn’t see any instance of this in the source)return []
SignatureObject.getDocumentationComment
getDocumentationComment([this.declaration], this.checker)
SymbolObject.getDocumentationComment
getDocumentationComment(this.declarations, checker)
SymbolObject.getContextualDocumentationComment
get
/set
stuff (I think).getDocumentationComment
I attempted to start inspecting what the
getDocumentationComment
function was being passed, but have not yet been able to get it working.No; rather I was suggesting a special casing wrt intersection types and the
Docs<T>
/DocsOf<T>
, so thatA & Docs<"blah">
would transfer the documentation, whileB & AWithDocs
would not.I agree that this inconsistency seems non-ideal, but I think it is reasonable:
A & Docs<"test">
reads cleaner thanDocumented<A, "test">
This is the “magic” I was talking about in my earlier comments; similar to how
ThisType
is handled specially.