Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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?

like image 857
Miquel Avatar asked Mar 20 '18 20:03

Miquel


1 Answers

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 */);

like image 145
vitaly-t Avatar answered Oct 20 '22 07:10

vitaly-t