Does not suppprt markdown content `@example`

[JounQin]

import { RULE_DISABLED, RULE_NOT_CONFIGURED } from '../constants.js'

/**
 * Checks if a given Prettier rule value is valid and configured.
 *
 * This function determines whether the provided Prettier rule value is set and
 * valid. It considers values as non-existent if they are `RULE_NOT_CONFIGURED`,
 * `RULE_DISABLED`, or `undefined`.
 *
 * @example
 *   ```ts
 *   console.log(ruleValueExists('always')); // Output: true
 *   console.log(ruleValueExists(RULE_DISABLED)); // Output: false
 *   console.log(ruleValueExists(undefined)); // Output: false
 *   ```
 *
 * @param {unknown} prettierRuleValue - The value of the Prettier rule to check.
 * @returns {boolean} `true` if the rule value exists and is valid, otherwise
 *   `false`.
 */
export const ruleValueExists = (prettierRuleValue: unknown): boolean =>
  prettierRuleValue !== RULE_NOT_CONFIGURED &&
  prettierRuleValue !== RULE_DISABLED &&
  prettierRuleValue !== undefined

After format:

I removed the markdown code block as workaround.

[JounQin]

Agly formatted:

/**
 * Create two functions that can be used to create both valid and invalid test
 * case to be provided to {@link TSESLintRuleTester}. This function accepts one
 * type parameter that should extend a {@link RuleModule} to be able to provide
 * the result with typed `MessageIds` and `Options` properties
 *
 * @example
 *   ```ts
 *   import { createRuleTestCaseFunction } from '../utils'
 *
 *   const ruleTester = new TSESLintRuleTester()
 *
 *   const { tValid, tInvalid } = createRuleTestCaseFunction<typeof rule>()
 *
 *   ruleTester.run(`no-useless-path-segments (${resolver})`, rule, {
 *   valid: [
 *   tValid({
 *   code: '...',
 *   }),
 *   ],
 *   invalid: [
 *   tInvalid({
 *   code: '...',
 *   }),
 *   ]
 *   })
 *   ```
 *
 * @param defaultOptions If you have a specific set of options that need to be
 *   passed to each test case you can supply them directly to this function.
 *
 *   If the `TRule` parameter is omitted default types are used.
 */

[fardad-dev]

Hi
remove '```ts' and '```'

[JounQin]

Hi remove 'ts' and ''

Hi, @hosseinmd, but markdown is valid in jsdoc @example? And also

Before:

/**
 * Type helper to build {@link TSESLintRuleTester.run} test parameters from a
 * given {@link RuleModule}
 *
 * @example
 *   const COMMON_TESTS: RunTests<typeof rule> = {
 *     valid: [
 *       {
 *         code: "import Foo from 'Foo';",
 *         options: [],
 *       },
 *     ],
 *     invalid: [
 *       {
 *         code: "import Foo from 'Foo';",
 *         options: ['prefer-top-level'],
 *         errors: []
 *       },
 *     ]
 */

After:

/**
 * Type helper to build {@link TSESLintRuleTester.run} test parameters from a
 * given {@link RuleModule}
 *
 * @example
 *   const COMMON_TESTS: RunTests<typeof rule> = {
 *   valid: [
 *   {
 *   code: "import Foo from 'Foo';",
 *   options: [],
 *   },
 *   ],
 *   invalid: [
 *   {
 *   code: "import Foo from 'Foo';",
 *   options: ['prefer-top-level'],
 *   errors: []
 *   },
 *   ]
 */

[fardad-dev]

it has syntax error change it to

/**
 * Type helper to build {@link TSESLintRuleTester.run} test parameters from a
 * given {@link RuleModule}
 *
 * @example
 *   const COMMON_TESTS: RunTests<typeof rule> = {
 *     valid: [
 *       {
 *         code: "import Foo from 'Foo';",
 *         options: [],
 *       },
 *     ],
 *     invalid: [
 *       {
 *         code: "import Foo from 'Foo';",
 *         options: ['prefer-top-level'],
 *         errors: []
 *       },
 *     ]
 *   }
 */

[JounQin]

So, we're not going to support valid markdown @example?

IMO, @example can also be used with other languages like sh for cli, and incomplete codes.

[JounQin]

Friendly ping @hosseinmd

[fardad-dev]

the description is fully support markdown, i think it is better to you remove @example tag and add code to description.

[Mister-Hope]

Coming from oxc-project/oxc#21549.

Oxfmt ported the code in oxc-project/oxc#19828.

The official docs https://jsdoc.app/tags-example does not clarity whether @example tag shall be allowed to followed by a fence.

But obviously, at least vscode supports it:

So, how shall we judge this unspecific behavior?

It's not affordable for me to receive code like this:

  /**
   * Xxx
   *
   * @example
   *   ;```html
   *   <a title="a">text</a>
   *   ```
   */