@deprecated tag in TS Definitions should be on the last position
d3xter666 opened this issue · 2 comments
Hello,
Currently @deprecated
tag (if such) goes as the first occurence into the JSDoc block of the TS definitions.
Please take a look at the currently generated definitions for UI5@1.120: https://www.unpkg.com/@sapui5/types@1.120.7/types/sap.ui.core.d.ts and search for @deprecated
tag.
An example:
/**
* @since 1.68
* @deprecated (since 1.119) - See class description for details.
*
* Provides access to the individual parameters of a URL query string.
*
* This class parses the query string from a URL and provides access to the values of individual parameters.
* There are methods to check whether the query string {@link #has contains a parameter (`has()`)}, to {@link #get get a single value (`get()`) }
* for a parameter and to {@link #getAll get a list of all values (`getAll()`)} for a parameter. Another
* method allows to {@link #keys iterate over all parameter names (`keys()`)}.
*
* Decoding:
*
* The constructor and the factory methods expect percentage encoded input whereas all other APIs expect
* and return decoded strings. After parsing the query string, any plus sign (0x2b) in names or values is
* replaced by a blank (0x20) and the resulting strings are percentage decoded (`decodeURIComponent`).
*
* Deprecation:
*
* This class is deprecated in favor of the URL web standard classes `URLSearchParams` / `URL`.
*
* `UriParameters.fromQuery(input)` can be migrated to `new URLSearchParams(input)`
*
* `UriParameters.fromURL(input)` can be migrated to `new URL(input).searchParams`
*
* Caveats:
*
* The API has already been designed to be a drop-in replacement but there are some important caveats to
* consider when switching to the standard APIs `URLSearchParams` / `URL`:
* - `new URL(input).searchParams` validates the given URL according to the WHATWG URL Standard ({@link https://url.spec.whatwg.org}).
* `UriParameters.fromURL(input)` only extracts the query string from the given input but does not perform
* any validation.
* - In some edge cases, especially for incomplete/invalid encoding, decoding behaves differently. Decoding
* in `UriParameters` is described in the section above. For details about the encoding/decoding of `URLSearchParams`,
* see the WHATWG URL Standard ({@link https://url.spec.whatwg.org}).
* - The `get` method's second parameter, `bAll`, is not available; use the `getAll` method instead.
* - The `keys` method's return value contains an entry for every occurrence of the key within the query,
* in the defined order and including duplicates. `UriParameters#keys()` yields unique key values, even
* when there are multiple values for the same key.
* - The internal `mParams` property is not available anymore (you should never access internal properties
* of UI5 classes or objects). With the predecessor of this API, access to `mParams` was often used to check
* whether a parameter is defined at all. Using the `has` method or checking the result of `get` against
* `null` serves the same purpose.
*/
export default class UriParameters {
The issue is that this enforces the JSDoc parser to take not only the @deprecated
line, but everything untill the next JSDoc tag (@link
s are not taken into account). In this case it's the whole descriptive JSDoc block.
That's indeed a bug in the generator. In JSDoc comments, block tags (like @deprecated
, @param
etc.) should come after the description. Or, the description has to be prefixed with @desc
.
Fix by @d3xter666 was applied internally for 1.121 and is also being downported to 1.120.