Comments (1)
This feature request is closely related to #3002 which asks for documenting/trimming members of a type
alias that mimics an interface
.
In general, type
can produce arbitrarily complex expressions that are difficult for API Extractor to model as "API items" the documentation website, and are not safe for .d.ts trimming. (Specifically, the concern is that trimming members may produce .d.ts rollups that fail to compile, and it can be difficult to detect or correct such cases, due to the expressiveness/flexibility of the type system.)
But in both cases, type
is being used for a restricted pattern that is very similar to an already supported API item kind:
#4699 involves a type
that looks like ApiEnum:
/**
* The icon size.
* @public
*/
export type IconSize =
/**
* 16x16 pixels
*/
'small' |
/**
* 32x32 pixels
* @beta
*/
'medium';
#3002 involves a type
that looks like ApiInterface:
export type Book = {
/** The title */
title: string;
/** The description */
description: string;
};
Thus, these particular patterns should be relatively well-behaved and straightforward to incorporate into the API item model. We could try to automatically detect them, but I think this would give a confusing experience. A seemingly small modification such as export type IconSize = 'small' | 'medium' | UnsupportedThing
could suddenly cause the API docs for 'small'
and 'medium'
to disappear from the website, because the expected pattern is no longer matched.
Proposed design
Let's call the above patterns formed types which means a type
that follows a predefined stereotypical form. The first example is a formed enum, and the second example is a formed interface, and in the future we could support more such patterns.
In this proposal, the user must declare the form explicitly, using new TSDoc tags such as @formedEnum
or @formedInterface
. For example:
/**
* The icon size.
* @formedEnum
* @public
*/
export type IconSize =
/** 16x16 pixels */
'small' |
/** 32x32 pixels */
'medium';
/**
* @formedInterface
* @public
*/
export type Book = {
/** The title */
title: string;
/** The description */
description: string;
};
With these tags, API Extractor will validate that the type
conforms to the supported structure, and report an error message if not. And then members such as 'small'
or title
will become ApiItem
objects in the model, with full support for .d.ts trimming and structured website documentation, just like ApiEnumMember
or ApiProperty
.
Whereas if you omit the @formedEnum
and @formedInterface
tags, then these declarations would instead become an ApiTypeAlias
whose members are just a blob of text in the signature without any special interpretation.
Implementation
The @formedEnum
and @formedInterface
features involve considerations and algorithms, so let's continue to track them using separate GitHub issues.
This issue #4699 I think is the easier one to start with. We've already confirmed that the TypeScript compiler correctly propagates all the /** */
comments to the .d.ts file. One slightly tricky aspect is the position of |
, for example...
export type IconSize =
/** 16x16 pixels */
'small' |
/** 32x32 pixels */
'medium';
...versus...
export type IconSize =
/** 16x16 pixels */
'small'
/** 32x32 pixels */
| 'medium';
...and what would we do with...
export type IconSize =
/** 16x16 pixels */
'small'
/** A */
|
/** B */
'medium';
We also need to decide whether to reuse ApiEnum
and ApiEnumMember
, or else define new model classes such as ApiFormedEnum
and ApiFormedEnumMember
. I don't have a strong opinion about this.
from rushstack.
Related Issues (20)
- [rush] feature request: support pnpm's `ignoredOptionalDependencies` setting in pnpm-config.json HOT 2
- [api-extractor] `@example` comment title line formatting is not preserved HOT 2
- [api-extractor] Imports are not correctly "trimmed" in rollups nor report variants HOT 1
- [api-extractor] Get error when rollup with specifying `module` to `Preserve`
- [rush] rush deploy does not copy files named with asterisk(*) HOT 2
- [rush] feature request: Azure Blob build cache AzurePipelinesCredential support HOT 3
- [rush] Rush plugin architecture doesn't support ESM? HOT 1
- [rush] Rush API for interacting with the Build Cache HOT 2
- [api-extractor] Error parsing tsconfig.json content: Unknown compiler option 'isolatedDeclarations'
- [api-documenter] Missing empty line after emitted HTML tags for tables
- [rush] rush build error logs no longer include stdout HOT 4
- [rush] package dependency ranges can resolve to different versions in the lockfile HOT 1
- [rush]
- [api-extractor] Support new TS .d.json.ts declaration pattern HOT 5
- [rush] Rush update should update shrinkwrap when globalPackageExtension has changed
- [eslint-patch] Error: Failed to patch ESLint because the calling module was not recognized. HOT 4
- [rush] how to support diffrent node version in diffrent app HOT 1
- [heft-web-rig] [build:sass] throw an error since version 0.24.29 : Error: The "paths[0]" argument must be of type string. Received undefined HOT 2
- [api-extractor] building with TS 5.6.2 causes error on wildcard import HOT 2
- [heft] typescript plugin does not work with Typescript 5.6.2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from rushstack.