jsdoc @example wasn't formatting code snippet.

[danielphilipjohnson]

• I moved "Defining a slice components" from the end of @example.
• It now formats the code

Types of changes

• [ ] Chore (a non-breaking change which is related to package maintenance)
• [x] Bug fix (a non-breaking change which fixes an issue)
• [ ] New feature (a non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to change)

Description

jsdoc @example wasn't formatting the code snippet. Ive now moved the text on the end of the line that was preventing it from working.

I found it hard to understand the code snippet due to not formatting.

Resolves #61

Checklist:

• [ ] My change requires an update to the official documentation.
• [ ] All TSDoc comments are up-to-date and new ones have been added where necessary.
• [ ] All new and existing tests are passing.

[codecov-commenter]

Codecov Report

Merging #62 (531ed15) into master (5e253e4) will increase coverage by 0.00%. The diff coverage is 100.00%.

@@           Coverage Diff           @@
##           master      #62   +/-   ##
=======================================
  Coverage   99.48%   99.48%           
=======================================
  Files          19       19           
  Lines        3084     3086    +2     
  Branches      160      160           
=======================================
+ Hits         3068     3070    +2     
  Misses         16       16           

Impacted Files	Coverage Δ
src/components/SliceZone.ts	99.64% <100.00%> (+<0.01%)	:arrow_up:

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[lihbr]

OK, I carried out some more research:

• @description isn't semantically valid for describing examples when considering JSDoc syntax so I'm really against it.
• JSDoc's @example, by its definition, just highlights code coming after, not what we want
• TSDoc's @example, is what we want, I'll try to make it work by the linter's

Edit: Well, looks like there's no way to disable the linter's behavior on these tags :[

[lihbr]

@angeloashmore may I summon your consult on that one (and the attached issue) so we can adopt the same solution everywhere 🤔

While a bit funky, I think separating the example description as Daniel did might be the more readable mitigation.

Curious how are examples being displayed within Vim also 🤔

[angeloashmore]

Vim/Neovim looks the same as VS Code, unfortunately. I assume the formatted content is sourced from the TypeScript service, which is why both editors suffer from the same issue.

As demonstrated in that function's example, any text after @example not in a code fence breaks support for code fences.

Adding the example's name outside the @example tags creates compatibility issues with the JSDoc Prettier plugin (prettier-plugin-jsdoc) which, despite the issue it presents here, is generally useful. I think we could come up with an alternative that lets us continue using prettier-plugin-jsdoc and @example tags as intended.

Proposal

One solution is to add example descriptions to the example's code block as a comment. I personally think this works better than separating the comment from the @example block since it keep the comment close to the example.

/**
 * @example
 *
 * ```javascript
 * // Defining Slice components.
 *
 * import { defineSliceZoneComponents } from "@prismicio/vue";
 *
 * // rest of the example...
 * ```
 */
export const defineSliceZoneComponents = // ...

It looks like this in Vim:

Any thoughts? We lose some semantic meaning of @example comments, but they don't seem to be used anywhere anyway.