* Parse comment on @property tag and use as documentation comment
* Fix comment parsing bug -- back up after seeing `@` character
* Add test for indent
* Don't default comment to ""
* Use documentation comments from inherited properties when @inheritDoc is present
The JSDoc `@ineheritDoc` [tag](http://usejsdoc.org/tags-inheritdoc.html)
"indicates that a symbol should inherit its documentation from its
parent class". In the case of a TypeScript file, this also includes
implemented interfaces and parent interfaces.
With this change, a class method or property (or an interface property)
with the `@inheritDoc` tag in its JSDoc comment will automatically use
the comments from its nearest ancestor that has no `@inheritDoc` tag.
To prevent breaking backwards compatibility,
`Symbol.getDocumentationComment` now accepts an optional `TypeChecker`
instance to support this feature.
fixes#8912
* Use ts.getJSDocTags as per @andy-ms 's recommendation
* Convert @inheritDoc tests to verify.quickInfoAt
* Concatenate inherited and local docs when @inheritDoc is present
* Make typeChecker param explicitly `TypeChecker | undefined`
* Re-accept baseline after switch to explicit `| undefined`
* Update APISample_jsodc.ts to match new getDocumentationComment signature
* Re-accept baselines after rebasing
* Add 'name' property to Identifier
* Rename to unescapedText
* Rename 'id.text' to 'id.escapedText'
* Rename 'id.unescapedText' to 'id.text'
* Make escapeIdentifier and unescapeIdentifier do nothing
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`.
* 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
