[spec] Adding snippets for "declaration references" #64
Conversation
…pec for TSDoc "declaration references"
| // a TypeScript "import" definition, so we don't discuss them further here. | ||
| // | ||
| // TSDoc declaration references are always resolved relative to a specific entry point | ||
| // (NOT relative to the current source file or declaration scope). Thus, their syntax |
There was a problem hiding this comment.
NOT relative to the current source file or declaration scope [](start = 4, length = 60)
This means that it's effectively impossible to refer to something that isn't exported from the package. #Resolved
There was a problem hiding this comment.
We can work around that by supporting relative imports. For example:
/**
* {@link ./lib/controls/Button:Button | referencing a local *.d.ts file}
*/I updated the note to explain this.
In reply to: 218613174 [](ancestors = 218613174)
| } | ||
|
|
||
| /** | ||
| * Shortest name: {@link Class00.member01[static]} |
There was a problem hiding this comment.
static [](start = 45, length = 6)
It'd be useful to have an example where there isn't both a static and instance member with the same name. #Resolved
| // Function overloads | ||
|
|
||
| /** | ||
| * Shortest name: {@link function06[1]} |
There was a problem hiding this comment.
1 [](start = 37, length = 1)
It would be helpful to warn against using this if you're talking about your own package (perhaps in strict mode) #Resolved
| /** | ||
| * Shortest name: {@link Class15."\uD842\uDFB7"} | ||
| * Full name: {@link Class15[class]."\uD842\uDFB7"[instance]} | ||
| * |
There was a problem hiding this comment.
Include alternatively:
Alternative name: {@link Class15[class].𠮷[instance]}
``` #Resolved
| /** | ||
| * Shortest name: {@link Class15.\{\}} | ||
| * JSON approach: {@link Class15."\u007B\u007D"} | ||
| * Full name: {@link Class15[class].\{\}[instance]} |
There was a problem hiding this comment.
There's a mistake with the escaping here. #Resolved
| * NOTE: The string in double quotes is parsed using JSON.parse(), which converts | ||
| * this surrogate pair expression to the corresponding Unicode character. | ||
| */ | ||
| public '𠮷': string = 'instance member using JSON unicode escapes'; |
There was a problem hiding this comment.
string [](start = 15, length = 6)
It might be useful to include an example of a member containing an allowed non-ASCII character (ß) #Resolved
| public '𠮷': string = 'instance member using JSON unicode escapes'; | ||
|
|
||
| /** | ||
| * Shortest name: {@link Class15."\\\""} |
There was a problem hiding this comment.
"\" [](start = 36, length = 5)
We should allow single- and double-quotes, and to escape a quotemark, double it. #WontFix
There was a problem hiding this comment.
I'm undecided on that one for now. We can add it later if needed.
In reply to: 218621886 [](ancestors = 218621886)
|
|
||
| /** | ||
| * Shortest name: {@link Class15."\uD842\uDFB7"} | ||
| * Full name: {@link Class15[class]."\uD842\uDFB7"[instance]} |
There was a problem hiding this comment.
uD842 [](start = 45, length = 5)
I don't think we should support unicode \u notation. #Resolved
| /** | ||
| * Shortest name: {@link Type16} | ||
| * Full name: {@link Type16[type]} | ||
| * |
There was a problem hiding this comment.
It might be interesting to have an example like this:
/**
* @type T - {@inheritdoc Y[class].X[type]}
*/
export class X<T> extends Y<string, X> {
}
``` #WontFix
There was a problem hiding this comment.
If we want to support this in the future, I think it can be incorporated without any significant changes to the notation. It seems like a fairly rare case, however, so in the interests of time I'm going to skip it for now.
In reply to: 218623575 [](ancestors = 218623575)
| */ | ||
| export interface Interface17 { | ||
| /** | ||
| * Shortest name: {@link Interface17.operator[STRING_INDEXER]} |
There was a problem hiding this comment.
operator [](start = 40, length = 8)
this won't work if you have a member called "operator"
What if you could say {@link Interface17.[STRING_INDEXER]} #Resolved
RFC issue #9 proposes a notation for "declaration references" that provide an unambiguous notation for referencing any API declaration such as classes, member functions, enum values, etc. This syntax will be used by standard tags such as
{@link}and{@inheritDoc}, and can also be used by custom tags.The proposed syntax supports edge cases such as:
Mr. Xorconstructoras object property names)new (hour: number, minute: number);)We also propose a new TSDoc inline tag
{@label YOUR_NAME}that can label a declaration for use by a reference.This PR is just a source file with a bunch of commented snippets, which will later be incorporated into the TSDoc spec document. My next PR will add a parser for this notation to the library.