Now Typescript supports the creation of anonymous types using successive
`@param` lines in JSDoc:
```js
/**
* @param {object} o - has a string and a number
* @param {string} o.s - the string
* @param {number} o.n - the number
*/
function f(o) { return o.s.length + o.n; }
```
This is equivalent to the Typescript syntax `{ s: string, n: number }`,
but it allows per-property documentation, even for types that only need
to be used in one place. (`@typedef` can be used for reusable types.)
If the type of the initial `@param` is `{object[]}`, then the resulting
type is an array of the specified anonymous type:
```js
/**
* @param {Object[]} os - has a string and a number
* @param {string} os[].s - the string
* @param {number} os[].n - the number
*/
function f(os) { return os[0].s; }
```
Finally, nested anonymous types can be created by nesting the pattern:
```js
/**
* @param {Object[]} os - has a string and a number
* @param {string} os[].s - the string
* @param {object} os[].nested - it's nested because of the object type
* @param {number} os[].nested.length - it's a number
*/
function f(os) { return os[0].nested.length; }
```
Implementation notes:
1. I refactored JSDocParameterTag and JSDocPropertyTag to
JSDocPropertyLikeTag and modified its parsing to be more succinct. These
changes make the overall change easier to read but are not strictly
required.
2. parseJSDocEntityName accepts postfix[] as in `os[].nested.length`,
but it doesn't check that usages are correct. Such checking would be
easy to add but tedious and low-value.
3. `@typedef` doesn't support nested `@property` tags, but does support
`object[]` types. This is mostly a practical decision, backed up by the
fact that usejsdoc.org doesn't document nested types for `@typedef`.
This means that JSDoc types can include the full range of Typescript
types now. It also means that Typescript annotations can include JSDoc
types. This is disallowed with a new error, however. But Typescript can
still give the correct types to JSDoc that shows up in .ts files by
mistake. This can easily happen, for example with types like
```ts
var x: number? = null;
var y: ?string = null;
var z: function(string,string): string = (s,t) => s + t;
// less likely to show up, but still understood.
var ka: ? = 1;
```
In the future, I will add a quick fix to convert these into the correct
types.
Fixes#16550
It's very ambiguous in expression position, so impossible to give a
better message from the parser. For example:
let f = (x: number) => number => x + 1;
~~
Should be ':'
But the parser doesn't know that 'number' isn't an expression now.
* Created a branded type for escaped strings
Then flowed it throughout the compiler, finding and fixing a handful of
bugs relating to underscore-prefixed identifiers in the process.
Includes a test for two cases noticed - diagnostics from conflicting
symbols from export *'s, and enum with underscore prefixed member emit.
* Correctly double underscores WRT mapped types
* Add fourslash tests for other fixed issues
* use function call over cast
* Update forEachEntry type accuracy
* Just use escaped names for ActiveLabel
* Remove casts from getPropertyNameForPropertyNameNode
* This pattern has occurred a few times, could use a helper function.
* Remove duplicated helper
* Remove unneeded check, use helper
* Identifiers list is no longer escaped strings
* Extract repeated string-getting code into helper
* Rename type and associated functions
* Make getName() return UnderscoreEscapedString, add getUnescapedName()
* Add list of internal symbol names to escaped string type to cut back on casting
* Remove outdated comments
* Reassign interned values to nodes, just in case
* Swap to string enum
* Add deprecated aliases to escapeIdentifier and unescapeIdentifier
* Add temp var
* Remove unsafe casts
* Rename escaped string type as per @sandersn's suggestion, fix string enum usages
* Reorganize double underscore tests
* Remove jfreeman from TODO
* Remove unneeded parenthesis
* Support completions for JSDoc @param tag names
* Undo change to finishNode
* Don't include trailing whitespace in @param range; instead, specialize getJsDocTagAtPosition
Nathan Shively-Sanders
AndyandGitHub
Wesley WighamandGitHub
Anders HejlsbergandGitHub
YuiandGitHub
Sheetal Nandi
Daniel RosenwasserandGitHub
Yui T
TravCavandMohamed Hegazy
Daniel Rosenwasser
Ron Buckton
Charles Pierce