More control over included jsdoc

[wycats]

Generally speaking, my goal is to render the docs differently from the types. The main reason for this is: while the types tend to be the right width for the container and look reasonably good, the docs frequently wrap weirdly. They also probably want to be rendered using markdown.

Here are some ideas that might help. I don't know the complete set of constraints, so I'd be happy with any progress along these lines.

1. The simplest improvement would be to put the jsdoc in a separate attribute (lsp-docs?), possibly with an opt-in. That would be enough to get the basic job done using CSS.
2. Slightly better from my perspective (but perhaps more problematic from yours): move the docs (and perhaps the types) into a child of the data-lsp node. This could also be opt-in.
3. You could also expose an option for formatting the docs (perhaps in conjunction with moving the rendered docs into a content node), which would make it possible to use a markdown formatter to format the docs.

If you did (3), it would probably be straight-forward to add an option to automatically format the docs using markdown in the markdown-it and remark plugins.

I can't tell precisely what the requirements are for this sort of thing just by reading the code, so please fire away if there's anything I missed or if there's any more information I can provide about my goals.

[orta]

Oops, absolutely missed this issue - sorry.

So there is some control atm, in that you can either have everything or nothing which is available via the option includeJSDocInHover

Here's an example of it in use on https://mael.dev/clipanion/

The JSDoc is jammed inside the data-lsp node:

<span style="color:#6F42C1">.<data-lsp lsp="Used to annotate positional options. Such options will be strings
unless they are provided a schema, which will then be used for coercion.

Be careful: this function is order-dependent! Make sure to define your
positional options in the same order you expect to find them on the
command line.

function String(): string (+8 overloads)">String</data-lsp></span>

Which I believe is appropriately escaped in order to safely be there, but I'm not 100% it covers all cases as we didn't use it on the TypeScript website (it would be too much info, which is often a bit more distracting from describing TS).

We basically pipe the direct response from TypeScript into the data-lsp, which means you can (probably) safely assume the last line is always the type and anything else is jsdoc.

I am indeed thinking about twoslash hover formatting #159 but mainly in the form of doing some TS type highlights in very few bytes - in Clipanion's case they use prismjs to colorize the types and maybe the jsdocs, but I think shipping a markdown processor is a bit much for us by default. That said, I think if you already have a runtime JS lib for highlighting, replacing the default JS which shows highlighting is a very reasonable way to get this right now

[wycats]

Whoops! I totally missed this. I think I can live with this for now, although it would be much nicer to be able to control what goes into the lsp node directly using the API. 😄