jsdoc @ 代码块内的字符

Posted 2023-03-13

【中文标题】jsdoc @ 代码块内的字符

【英文标题】：jsdoc @ character inside code block

【发布时间】：2018-08-29 20:10:15

【问题描述】：

我正在尝试为这样的模块函数编写文档：

/**
 * 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。

有什么建议吗？

【问题讨论】：

这是asked 5 years ago 没有答案，也是compodoc 中的一个突出问题

【参考方案1】：

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

```js
@Module
```

这将产生正确的@Module 输出。

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

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

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

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

【参考方案2】：

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

【讨论】：

唯一的解决办法，应该是公认的答案