-
Notifications
You must be signed in to change notification settings - Fork 592
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[api-extractor] Support docs/trimming for members of an interface-like "type" alias #3002
Comments
Didn't want to comment on the pull request but I'm interested in this feature as well. The documentation being generated for react components using |
The TypeScript compiler owners view language features in terms of type algebra, in other words compiler syntax and semantics. For example, when comparing these alternatives, their docs will focus on technical details such as inheritance or assignability or
API documentation has a somewhat different perspective, based around how humans discuss code and the different engineering cultures behind that. For the large corporate code bases that inspired API Extractor, historically we have tended to prefer standard coding stereotypes over flexible free-form expressions. For example, "a function" is a friendlier concept than "a constant variable whose data type is a lambda." And "an interface" is a friendlier concept than "a type signature describing a non-nested object without any alternatives." Building your API from standardized bricks makes it easier for beginners to learn, easier to organize the docs, and easier to talk about when providing support. This is why API Extractor's generated documentation groups API pages into classes, enums, interfaces, etc. Declarations that don't fit into one of these stereotypical forms are allowed, but they get rendered as an unstructured blob of type algebra. However the TypeScript language has grown a lot over the years, so it makes sense to broaden the set of recognized patterns. (My point is that we should do that by introducing more stereotypes, not dispensing with them entirely; I don't know how to make a friendly documentation index for totally arbitrary type algebra.🙃 )
In your example, the type alias has the same shape as an But keep in mind that export type Example1 = {
/** Docs for string A */
a: string;
} | {
/** Docs for number A */
a: number;
};
export type Example2 = {
/** Docs for A */
a: string;
} & (
{
/** Docs for B */
b: string;
}
|
{
/** Docs for C */
c: string;
}
);
export type Example3 = {
/** Docs for A */
a: string;
} | true | undefined;
/** @param a - Docs for A */
export type Example4 = (a: string) => {
/** Docs for B */
b: string;
}; These expressions deviate from your original example in different ways. A developer might consider them to be small incremental changes, but at some point API Extractor will suddenly stop modeling them correctly and the member documentation will disappear from the website. In order to accept your PR #3002, we need to solve three design problems:
I don't expect this to be a lot of coding, just considering a bigger set of input cases and how they should be handled. |
Thanks @octogonz. Those are good points about why type aliases are more difficult and we need to be careful. For the record, I think my current solution handles examples 2-4 reasonably well (I don't know how I would display it any differently) but it definitely should change for example 1. The tl;dr is that since this just adds property tables to what was otherwise there already, so as long as those property tables are correct, I don't think there's much downside to adding them. The only case I see where the property table is incorrect is in example 1, and that's because there are multiple property definitions for the same property name. Since they conflict, it just takes the first one. For the others though, you can see the definition the same as without my change, you just get more readable per-member documentation for the members as you see them in the code snippet. So i guess to answer your questions.
thoughts? |
We use types for react components and in general for the more functional aspects of our codebase and interfaces for the more object-oriented parts. From my understanding that's the useful divide for when to use one over the other. We chose to use api-extractor because it isn't coupled to a specific framework/library like react-docgen. Not sure if this is any help. The documentation we're generating right now with api-extractor isn't great because the codebase is mostly functional. I'm going to look closely at the documentation and come up with some, hopefully, constructive criticism that may be helpful for informing a design on this stuff |
Hi @octogonz any thought on my comment above? |
@bdwain 🤔 Generally we've tried to avoid this sort of heuristic. For example, certain API Documenter targets will create a separate web page with its own URL for each interface property. Suppose I had a declaration like this: /** `http://example.com/api/widgets.t` */
type T = {
/** `http://example.com/api/widgets.t.a` */
a: string;
/** `http://example.com/api/widgets.t.b` */
b: string;
} | {
/** `http://example.com/api/widgets.t.c` */
c: string;
} ...and then someone comes along and adds one more property: /** `http://example.com/api/widgets.t` */
type T = {
a: string;
b: string;
} | {
b: number; // <-- oops
c: string;
} It would be counterintuitive that such a "small incremental change to what was already there" might suddenly cause 3 web pages to silently disappear from the internet. And all those I bet we could solve this problem, for example by inventing separate property nomenclature like |
#4699 requests something similar for enum-like types. A design proposal for both features is written up here: #4699 (comment) |
Summary
Can support for type aliases be added? They are basically equivalent, but only interface fields can be documented. https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#differences-between-type-aliases-and-interfaces
Details
looking at the generated AST, it looks like interfaces have a
members
array ofPropertySignature
s, each with adocComment
. When the equivalent is done with type aliases, it only has an array ofexceptTokens
Standard questions
Please answer these questions to help us investigate your issue more quickly:
@microsoft/api-extractor
version?node -v
)?The text was updated successfully, but these errors were encountered: