jsdoc @字符在代码块中

Question

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

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

问题出在哪里@NgModule。我尝试过：

* ```
* @NgModule

似乎html实体在代码（```）外部运行良好，但在代码块内部却行不通（这有点奇怪，就像NgModule用粗体和换行表示）

也试过\@，{@literal @}，\u0064，@@没有成功。我发现最友好的是(@)NgModule。

有什么建议吗？

Answer 1

我很幸运在 unicode 空间中使用了替代 @ 符号：U+FF20 (\xef\xbc\xa0)。它使文档看起来正确，但不幸的是，如果有人复制/粘贴代码块，它就不起作用。至少从 2012 年开始，这似乎就是一个悬而未决的问题，所以我不会屏息以求更好的解决方案。

\n

Answer 2

遗憾的是，@example块内的 jsDoc 不支持特殊符号。它们只在内联代码块中工作，如下所示：

```js
@Module
```

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

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

当您想在代码示例中使用多行注释等内容时，情况也是如此。

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

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