@example tag titles cannot be derived from CommentTag type

[achingbrain]

Search terms

• example tag
• title

Actual Behavior

The tsdoc website says:

Any subsequent text that appears on the same line as the @example tag should be interpreted as a title for the example.

The example is parsed as a CommentTag which has content and tag fields and an optional name field.

Any text on the same line as the @example tag appears in the content list along with any other text.

E.g.

/**
 * @example This is how to do a thing
 *
 * Here is some more explantation.
*/

Becomes:

{
  tag: "@example",
  content: [{
    kind: "text",
    text: "This is how to do a thing\n\n"
  }, {
    kind: "text",
    text: "Here is some more explantation.\n\n"
  }]
}

So it's impossible to tell if there was a title for the example.

Expected Behavior

The CommentTag.name field docs say:

Some tags, (@typedef, @param, @property, etc.) may have a user defined identifier associated with them. If this tag is one of those, it will be parsed out and included here.

So if present, the example title should probably be in the name field?

{
  tag: "@example",
  name: "This is how to do a thing",
  content: [{
    kind: "text",
    text: "Here is some more explantation.\n\n"
  }]
}

Environment

• Typedoc version: 0.25.3
• TypeScript version: 5.2.2
• Node.js version: 20.8.0
• OS: Mac OS X 13.5.1

[Gerrit0]

This seems like a reasonable way to handle things 👍 JSDoc <caption>s should be put there too.

[Gerrit0]

Hmm... and what happens if there's a {@link} in the first line? name is a string, so can't support complex content.

VSCode doesn't support this idea as a thing, just rendering it on the next line after the block.

Since TS doesn't even parse @link tags in @example blocks, it's probably reasonable to assert that they just can't appear there, and will be treated as regular text, but that feels ugly. The alternative is a new heading?: CommentDisplayPart[] attribute on CommentTag... which feels ugly. I'm leaning towards name right now, and emitting a warning if the heading contains rich content. Going to let this one sit for a while before deciding...

If you toss an @example block with a heading into https://tsdoc.org/play/, the official parser's AST doesn't place it somewhere you can tell either. It looks like I'm not the first to notice this. API extractor (the "official" tsdoc documentation generator written by the microsoft people who wanted TSDoc to begin with) doesn't mention this feature in their docs either, so I suspect don't support it

[achingbrain]

I'm leaning towards name right now, and emitting a warning if the heading contains rich content.

This seems reasonable to me. I guess any more might need a change to the tsdoc specs?