jsdoc @ character inside code block

问题

I'm trying to write documentation for a Module function like this:

/**
 * Usage:
 *
 * ```
 * @NgModule({
 *      imports: [
 *          BrowserModule,
 *          ...,
 *          ThisModule.forRoot({
 *              name: 'Name',
 *              version: '1.0',
 *      ],
 * }),
 * ```
 * 
 * @param config Service configuration parameters
 */
public static forRoot(config: SVConfig) {

The problem is with @NgModule. I've tried with:

* ```
* @NgModule

Seems that html entitites works well outside code (```), but not inside code block (it does something weird like making NgModule in bold and new line)

Also tried \@, {@literal @}, \u0064, @@ with no success. The most friendly I've found is (@)NgModule.

Any suggestion please?

回答1:

Sadly, special symbols are not supported in jsDoc inside @example block. They work only inside inline code blocks, like this one:

```js
@Module
```

This will result in the proper @Module output.

And unlike @example, you cannot place an inline code block after everything, because it is inline, which means it will be somewhere before your @returns section. Awkward, I know.

The same goes when you want to use something like multi-line comment in your code example, etc.

```js
a.setParams(/* parameters here */);
```

outputs: a.setParams(/* parameters here */);

回答2:

I've had luck using an alternate @ symbol in the unicode space: U+FF20 (＠). It makes the documentation look correct, but unfortunately won't work if someone copy/pastes the code block. This appears to be an open issue since at least 2012 so I'm not holding my breath for a better fix.

来源：https://stackoverflow.com/questions/49393923/jsdoc-character-inside-code-block