JSDoc：代码块中的@字符

Question

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

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

有什么建议吗？

- Miquel

---

这个问题在5年前被提出（https://dev59.com/QWkv5IYBdhLWcg3w91hF），但没有得到解答，并且在compodoc（https://github.com/compodoc/compodoc/issues/304）中仍然存在。 - Sam Herrmann

Answer 1

我曾经尝试在Unicode空间中使用另一个@符号：U+FF20 (＠)。这使得文档看起来更加正确，但不幸的是，如果有人复制/粘贴代码块，则无法正常工作。自2012年以来，这似乎是一个待解决的问题，所以我并不指望有更好的解决方法。

- psaxton

---

唯一可行的解决方案应该被接受为答案。 - ktutnik

Answer 2

遗憾的是，在 @example 块中，jsDoc 不支持特殊符号。它们只能在内联代码块中使用，例如：

```js
@Module
```

这将导致适当的@Module输出。

而且，与@example不同的是，你不能在每件事后面放置一个内联代码块，因为它是内联的，这意味着它将在@returns部分之前某个地方。很尴尬，我知道。

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

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

输出: a.setParams(/* 在此处输入参数 */);

- vitaly-t

Answer 3

我想到的最接近的方法是在 @ 符号之前使用 Invisible Separater。

e.g.:

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

在VSCode中，它会看起来像这样：

警告：

如果有人复制粘贴在VSCode中显示的评论，代码将无法正常工作，因为它也会复制这个不可见字符。VSCode可能会报告存在无效字符的错误。

- Eranga Heshan