@description tag missing from default

[Bugs5382]

Search Terms

description,since,block

Problem

Like @since (#2614), @description is a valid JSdoc tag. When properly used in an IDE it shows up like this:

From:

To:

... in the rendered view indicating more description/expanding from the "title." It might have been removed as the default by accident.

Suggested Solution

I am working on a PR.

[Gerrit0]

If there's both a description at the beginning of a JSDoc comment and a description provided with the @description tag, the description specified with the@description will override the description at the beginning of the comment. - JSDoc

This behavior is not respected by typedoc, and frankly it sounds like a terrible idea to me, which is why @description is not included in the list of default tags.

As your IDE obviously isn't following this behavior either, my question is - why is this tag useful over just including a paragraph break in the comment summary section?

/**
 * Some docs
 *
 * More docs that were previously under `@description
 */

[Bugs5382]

@Gerrit0 I see the “title” of the function/code as one thing and a more description about what it does in its own section. While I can see this as a burden to add, JSDOC shows https://jsdoc.app/tags-description being a type. Though it notes that the tag overrides the rest of the comment.

The https://jsdoc.app/tags-summary tag seems to be the “short” description and/or summary of what the long stuff. Maybe switch this out for @summary ,,,,

[Gerrit0]

It sounds like what you want is provided by TypeDoc's @remarks tag.

The @summary tag isn't a great fit either as typedoc renders the non-tagged content first.

[Bugs5382]

@Gerrit0 Remarks it is! 👍