jsdoc @字符在代码块内 [英] jsdoc @ character inside code block

问题描述

我正在尝试为类似Module的功能编写文档:

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) {

问题出在@NgModule上.我尝试过:

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

* ```
* @NgModule

似乎html实体在代码(```)外部有效，但在代码块内部无效(这很奇怪，就像用粗体和换行形式表示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)

也尝试了\@，{@literal @}，\u0064，@@，但均未成功. 我发现最友好的是(@)NgModule.

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

有什么建议吗?

推荐答案

遗憾的是，@example块中的jsDoc不支持特殊符号.它们仅在内联代码块内工作，例如以下代码:

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

```js
@Module
```

这将导致正确的@Module输出.

与@example不同，您不能在所有内容之后放置一个内联代码块，因为它是内联的，这意味着它将位于您的@returns节之前的某处.尴尬，我知道.

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

输出:a.setParams(/* parameters here */);

这篇关于jsdoc @字符在代码块内的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！