如何在NetBeans中的JSDoc注释中转义@符号

Question

我在API中有一个简单的方法，可以使用JSONPath搜索对象。由于其语法对于初级开发人员来说相当陌生，因此我决定在JSDoc注释中提供一些示例。然而，这里有个问题，@符号被视为新jsdoc标签的开始，因此描述会变得损坏。

问题：如何使NetBeans（或通用的jsdoc）忽略特定代码块内部的@符号？最好是在@example块中实现。

因此，该代码将显示未经修改的工具提示：

$..book[?(@.price<10)] //-过滤所有价格低于10美元的书籍

@example、<code>、<pre>也无法解决这个问题。

在工具提示中，Html实体@将转换为@，但它在代码本身中看起来不可读（$..book[?(&#64;.price<10)]），并且仅适用于主要的jsdoc文本...

- c69

---

@ignore 可能有效。 - Paul Sweatte

Answer 1

这是一个比较老的问题，但我在使用VSCode时也遇到了同样的问题，我想分享可能的解决方法。

最后有效的方法是将 @returns 移到示例下面，不幸的是，不能使用 @example，例如：

/**
 * some description
 * 
 * For example:
 * ```js
 * $..book[?(@.price<10)] // - filter all books cheaper than 10
 * ```
 * @returns {*} whatever you're returning
 */

这并不是最理想的方式，但适用于VSCode的工具提示；我不确定它是否适用于NetBeans。

- Scott Rudiger

---

如果你下载了Netbeans并检查它是否可以正常工作，我将非常乐意接受这个答案。附注：我自己的机器上没有安装Netbeans，因此无法验证它。 - c69

Answer 2

不确定是否适用于所有环境，但在使用VSCode编辑typescript (.ts)文件时，我可以使用模板字符串来实现漂亮的示例代码显示。

/**
 * @description
 * This function totally does something.
 *
 * @example```
import { SomeThing } from '@mycompany/my-cool-library';

DoSomething(SomeThing)```
 * 
 * @returns string
 */

使工具提示显示为：

- Glorifundel

---

这对我也不起作用，但将字符串变为模板字符串可以解决问题，因此在字符串周围使用`而不是'，其中包含@。 - ndonohoe