Provide a way to give users a good experience via linking both when using the package in IDE vs scanning the TypeDoc.
I want to provide links to types that make sense to use for various types. I want this to improve developer experience both for TypeDoc
and when using the package itself via VSCode's inline documentation. We should be able to use them together without importing everything directly.
HOWEVER, this is impossible:
{@link enums.OrderTypes}
{@link enums.OrderTypes}
So TypeDoc would REQUIRE {@link OrderTypes}
and it will try to find things directly instead of realizing I imported enums
and I am referring to the OrderTypes on the enums
import.
{@link enums.OrderTypes}
import type * as enums from '../enums';
export interface Random {
/**
* @see enum {@link enums.OrderTypes}
* @see type {@link enums.OrderType}
*/
type: enums.OrderType;
}
{@link OrderTypes}
import type * as enums from '../enums';
export interface Random {
/**
* @see enum {@link OrderTypes}
* @see type {@link OrderType}
*/
type: enums.OrderType;
}
What is notable here is that it obviously understands this kind of linking... because I am using
enums.OrderType
for the type itself andtypedoc
links to it flawlessly in that situation.
We can also see that a typescript team member seems to confirm this is a bug with TypeDoc
microsoft/TypeScript#16498 (comment)
Welcome to the horrible world that is trying to build software that has conflicting requirements from several groups of people and trying to make one group happy breaks another. Something I've wanted to try for a while is see if links can be resolved by TS, and if not fall back to TypeDoc's current implementation, but have been busy recently, so haven't done anything on typedoc.
It's worth mentioning that "works in vscode" is also not good enough, because what works in your .ts files may no longer work once the comment is copied into a .d.ts file during compilation... so it might work for you, but not for your library's consumers. I suspect this is part of why the tsdoc team went with global resolution.
Owner Name | TypeStrong |
Repo Name | typedoc |
Full Name | TypeStrong/typedoc |
Language | TypeScript |
Created Date | 2014-05-24 |
Updated Date | 2023-03-19 |
Star Count | 6487 |
Watcher Count | 68 |
Fork Count | 639 |
Issue Count | 48 |
Issue Title | Created Date | Updated Date |
---|