feat: Add --raw-jsdoc option to include full JSDoc in schema

[alexchexes]

This adds support for a new CLI/config option --raw-jsdoc (rawJsDoc), which includes a rawJsDoc field in the generated JSON Schema. This field preserves the full JSDoc comment block as is (after removing asterisks), without any formatting, tag filtering, inheritance, etc.

• Adds CLI and config option: --raw-jsdoc / rawJsDoc
• Adds rawJsDoc keyword to Ajv validator
• Enhances ExtendedAnnotationsReader to extract raw JSDoc when available
• Includes thorough tests in test/config/jsdoc-raw
• Updates documentation (README)

Related to discussion in #1544 and complements --markdown-description (#1773)

Example:

Typescript:

/**
 * **Summary**
 * Link {@link https://example.com}
 * @description Short summary
 * @see Reference
 * @see https://example.com
 * - Additional comment
 */

Output:

{
  "description": "Short summary",
  "markdownDescription": "**Summary**\nLink  {@link  https://example.com }",
  "rawJsDoc": "**Summary**\nLink {@link https://example.com}\n@description Short summary\n@see Reference\n@see https://example.com\n- Additional comment"
}

[Copilot]

Copilot reviewed 7 out of 8 changed files in this pull request and generated no comments.

Files not reviewed (1)

• test/config/jsdoc-raw/schema.json: Language not supported

[arthurfiorette]

I already did not like going out of the JSDoc spec with markdownDescription. Not sure how I feel about another description-related field. What about rawJsDoc being a flag that puts the raw JSdoc contents inside the description, so we don't create a new field?

[arthurfiorette]

Wrongfully approved.

[domoritz]

Instead of another command, we should combine it with --markdown-description and make the option an enum.

[arthurfiorette]

Awesome, enum value seems better :)

[alexchexes]

What about rawJsDoc being a flag that puts the raw JSdoc contents inside the description, so we don't create a new field?

That was actually my first idea too — to reuse the description field for raw JSDoc — but while exploring it, I realized it forces users to choose between either the parsed description (with tags stripped and formatting normalized) or the raw JSDoc as originally written.

Replacing description would break the default behavior and potentially affect tooling or users who rely on it for readability or validation, yet those users (just like myself) could also need the full, unformatted, and unstripped JSDoc.

So, while I initially wasn't a big fan of introducing a new field either, adding a separate rawJsDoc field turned out to be the safest and least disruptive option.

@domoritz
Regarding the enum idea — do you mean something like this?

--jsdoc-description parsed      # only includes description (default)
--jsdoc-description markdown    # includes description + markdownDescription
--jsdoc-description raw         # includes description + rawJsDoc
--jsdoc-description full        # includes all: description + markdownDescription + rawJsDoc

That would definitely simplify the config surface and avoid introducing another CLI flag, so if we all agree this is a good approach, I can rework the PR in that direction.

[arthurfiorette]

It's an opt-in feature, so it shouldn't break anything by default. The user should know why they chose it.

jsdoc-description seems a good name fit.

---

It would be good if we could remove --markdown-description from the documentation but still interpret it, just as if it were --jsdoc-description markdown alongside it, emit a deprecation warning.

[alexchexes]

It's an opt-in feature, so it shouldn't break anything by default. The user should know why they chose it.

By "break the default behavior," I meant that overwriting the description with the raw JSDoc would change what tools and users might expect (even when they opt in for raw JSDoc) — a short, clean summary string without special at-tags, etc.

There are real cases where both are useful: for example, showing a concise description inline, while exposing the full rawJsDoc in a tooltip, collapsible developer panel, or markdown preview.

If we allow only one at a time, then in such cases the user would have to generate the schema twice with different options and invent a strategy to merge them. That doesn't feel like a clean approach. At the same time, I can imagine cases where you do want the raw JSDoc to go into the description field — for example, if a tool only supports description and you can't make it recognize custom fields like rawJsDoc. Definitely a bit of a dilemma...

jsdoc-description seems like a good name fit.

Agreed! The only question is: what option values should we support?
Something like parsed | markdown | raw | full as described above?

[alexchexes]

Agreed! The only question is: what option values should we support?
Something like parsed | markdown | raw | full as described above?

So, what are we doing? 🙂

[domoritz]

--jsdoc-description parsed      # only includes description (default)
--jsdoc-description markdown    # includes description + markdownDescription
--jsdoc-description raw         # includes description + rawJsDoc
--jsdoc-description full        # includes all: description + markdownDescription + rawJsDoc

Hmm, after seeing this, I think actually what you have (no enum) makes more sense. It lets users enable and disable whatever they need.

[domoritz]

Should this be --raw-jsDoc since we have --jsDoc already?

[alexchexes]

Honestly, I would replace --jsDoc with --jsdoc or --js-doc, but that's up to you guys

[domoritz]

I'd too if we started over but let's not break it now.

[domoritz]

It would be good if we could remove --markdown-description from the documentation but still interpret it, just as if it were --jsdoc-description markdown alongside it, emit a deprecation warning.

Or do we want to get rid of markdown-description in favor of this option? Then it might be worth revisiting all the options we have related to descriptions and make sure they are understandable. I like having fewer config options.

[arthurfiorette]

Some users might rely on markdown description, but that's probably because we don't yet provide raw JSdoc. As soon as we provide raw JSdoc, it's up to the user to parse the raw JSDoc into markdown however they want...

[alexchexes]

Some users might rely on markdown description, but that's probably because we don't yet provide raw JSdoc. As soon as we provide raw JSdoc, it's up to the user to parse the raw JSDoc into markdown however they want...

So, is the plan to deprecate --markdown-description for now and recommend using the rawJsDoc option instead?
Are we adding a rawJsDoc field that will eventually replace the markdownDescription field?

[arthurfiorette]

Up to @domoritz decide :)