How to escape @ sign inside JSDoc comments in NetB

问题:

I have a simple method in API, that allows searching objects with JSONPath. As its syntax is pretty much unfamiliar to junior developers, i decided to provide some examples within JSDoc comment. Yet, here is the catch, - @ sign is treated as a start of new jsdoc-tag, and so description becomes corrupted.

Question: how to make NetBeans (or jsdoc in general) ignore @ signs inside of particular code chunk ? Preferably, within @example block.

So this code, would show unmodified within tooltip:

$..book[?(@.price<10)] // - filter all books cheaper than 10

Also, @example, <code>, <pre> - do not help.

Html entity @ is converted to @ in tooltip, but it looks unreadable in the code itself ($..book[?(&#64;.price<10)]) and its only working in main jsdoc text ...

回答1:

This is a pretty old question, but I was having the same problem, except in VSCode and thought I'd share a possible solution.

What finally worked was moving @returns below the example and, unfortunately, not using @example, e.g.:

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

This is not ideal, but works for VSCode's tooltip; I'm not sure if it'll work with NetBeans.

回答2:

Not sure if this will work for all environments, but when using VSCode on a typescript (.ts) file I was able to use template strings to achieve nicely displayed example code

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

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

Makes the tooltip display like: