[BUG] Detect decorators as a JSDoc tag inside @example block.

[HamedFathi]

TypeScript Version: 3.7.2

Code

/**
 * Component that creates log event objects based on raw inputs sent to 'ILogger'.
 *
 * To customize what data is sent to the sinks, replace the implementation for this interface with your own.
 *
 * @example
 *
 * @singleton
 * export class MyLogEventFactory {
 *   public createLogEvent(logger: ILogger, logLevel: LogLevel, message: string, optionalParams: unknown[]): ILogEvent {
 *     return {
 *       logLevel,
 *       optionalParams,
 *       toString() {
 *         return "aaa";
 *       }
 *     };
 *   }
 * }
 *
 * container.register(Registration.singleton(ILogEventFactory, MyLogEventFactory));
 */
export interface ILogEventFactory {
}

I want to get JSDoc tags, TS compiler detects @singleton as a tag but it is not. It is a decorator in the @example block.

Expected behavior:

Ignore decorators inside the @example block of JSDoc.

Actual behavior:

returns decorator as a tag!

[nmain]

There doesn't seem to be a formal specification for JSDoc syntax, so syntactically speaking, how would the compiler disambiguate this?

[HamedFathi]

@nmain

At least, we should be able to use an escape character to ignore/avoid tag recognition by TS compiler.

For example: \@singleton

/**
 * Component that creates log event objects based on raw inputs sent to 'ILogger'.
 *
 * To customize what data is sent to the sinks, replace the implementation for this interface with your own.
 *
 * @example
 *
 * \@singleton
 * export class MyLogEventFactory {
 *   public createLogEvent(logger: ILogger, logLevel: LogLevel, message: string, optionalParams: unknown[]): ILogEvent {
 *     return {
 *       logLevel,
 *       optionalParams,
 *       toString() {
 *         return "aaa";
 *       }
 *     };
 *   }
 * }
 *
 * container.register(Registration.singleton(ILogEventFactory, MyLogEventFactory));
 */
export interface ILogEventFactory {
}

[dsherret]

@HamedFathi just looked into this and I believe this needs to be @singleton? https://stackoverflow.com/a/53556016/188246

I found that works for me and displays properly in VS code.

[HamedFathi]

@dsherret

Although, I prefer an escape character to a unicode value! just like my sample because It is more beautiful and readable but your suggestion is so good. Thanks.

[typescript-bot]

This issue has been marked 'Working as Intended' and has seen no recent activity. It has been automatically closed for house-keeping purposes.

[Frikki]

@HamedFathi and @RyanCavanaugh, I don’t see this working as intended.

[dsherret]

@Frikki it's not working for me anymore either in VS code 1.41.1, but I'm pretty sure it did before. I found it only works if I put that code in code blocks now.

Might be worth it to open an issue in the vscode repo, but I'm not 100% sure what the expected behaviour is.

[Frikki]

@dsherret Thanks for following up on this. I would expect that it should be possible to type @ symbols in a code block even when it follows an @example block, without breaking the VSCode display.

[brokenmass]

@dsherret @Frikki : I'm having the same problem but i'm not able to get the @ symbol to work properly in vscode (1.41.1).

/**
 * description
 *
 * ```ts
 * @singleton
 * export class MyClass {}
 * ```
 *
 * ```ts
 * @singleton
 * export class MyClass {}
 * ```
 */

renders as:

*@singleton*  
export class MyClass {}
@singleton
export class MyClass {}

[nicobrinkkemper]

Sorry for the +1, but this still seems to be an issue. I'm running in to it trying to add common custom html5 element code with Typescript.

Take the following example

/**
 * Decorator pattern to define custom elements
 *
 * @example
@defineCustomElement('app-rating')
class AppRating extends HTMLElement {

 * @param {string} name The name of the custom element
 */

As I see it right now, this forces developers to choose between two options:

1. Add a space before the @
   -> hovering over the function will not show proper color/code highlighting but will show the
2. Remove the @
   -> code shows proper highlighting, but doesn't show the @ obviously so it's technically a incorrect example

What I've tried: result

• Wrapping with ``` : shows the @ but does not show proper code highlighting
• Escape char with \ , unintended space added and * signs added
• Adding @ will just print @ instead of @

[trusktr]

@

This is highly unreadable in the source comment.

[trusktr]

In case anyone missed it, #47679 is open and hopefully will finally provide a solution.

[kasir-barati]

Ah, god when will this be fixed?