Keep prose that applies to the whole block at the block level

[turadg]

In our codebase, we have a large number of @typedef and @callback. Per JSDoc examples (linked) we keep the prose fully to the left:

For example,

/**
 * @template {AssetKind} [K=AssetKind]
 * @typedef {object} Amount
 * Amounts are descriptions of digital assets, answering the questions
 * "how much" and "of what kind". Amounts are values labeled with a brand.
 * AmountMath executes the logic of how amounts are changed when digital
 * assets are merged, separated, or otherwise manipulated. For
 * example, a deposit of 2 bucks into a purse that already has 3 bucks
 * gives a new purse balance of 5 bucks. An empty purse has 0 bucks. AmountMath
 * relies heavily on polymorphic MathHelpers, which manipulate the unbranded
 * portion.
 *
 * @property {Brand<K>} brand
 * @property {AssetValueForKind<K>} value
 */

/**
 * @callback ShutdownWithFailure
 * Called to shut something down because something went wrong, where the reason
 * is supposed to be an Error that describes what went wrong. Some valid
 * implementations of `ShutdownWithFailure` will never return, either
 * because they throw or because they immediately shutdown the enclosing unit
 * of computation. However, they also might return, so the caller should
 * follow this call by their own defensive `throw reason;` if appropriate.
 *
 * @param {Error} reason
 * @returns {void}
 */

However because we have the prose beneath the tags they qualify, in version 0.3.32 these are reformatting to:

/**
 * @template {AssetKind} [K=AssetKind]
 * @typedef {object} Amount Amounts are descriptions of digital assets,
 *   answering the questions "how much" and "of what kind". Amounts are values
 *   labeled with a brand. AmountMath executes the logic of how amounts are
 *   changed when digital assets are merged, separated, or otherwise
 *   manipulated. For example, a deposit of 2 bucks into a purse that already
 *   has 3 bucks gives a new purse balance of 5 bucks. An empty purse has 0
 *   bucks. AmountMath relies heavily on polymorphic MathHelpers, which
 *   manipulate the unbranded portion.
 * @property {Brand<K>} brand
 * @property {AssetValueForKind<K>} value
 */

/**
 * @callback ShutdownWithFailure Called to shut something down because something
 *   went wrong, where the reason is supposed to be an Error that describes what
 *   went wrong. Some valid implementations of `ShutdownWithFailure` will never
 *   return, either because they throw or because they immediately shutdown the
 *   enclosing unit of computation. However, they also might return, so the
 *   caller should follow this call by their own defensive `throw reason;` if
 *   appropriate.
 * @param {Error} reason
 * @returns {void}
 */

Moving the text to start on the line makes a lot of sense for tags that describe features of the JSDoc block but seems unnecessary for ones that are about the whole block (e.g. @typedef and @callback). Moving it actually makes the text harder to read.

As a workaround we could move the prose above the tags, but I think that would still be less readable. In a @typedef block the first thing we want to see is what type is being defined. (Not to mention the significant manual effort.)

[hosseinmd]

You can use jsdocSeparateTagGroups to add an empty line between @Property and @typedef or @callback.

[hosseinmd]

But for consistency, it's applying everywhere.

[turadg]

When I enable jsdocSeparateTagGroups it does this, as expected,

  * @callback AddVaultType
+ *
  * @param {Issuer} collateralIssuer
  * @param {Keyword} collateralKeyword
  * @param {Rates} rates
+ *
  * @returns {Promise<VaultManager>}

But it doesn't change the behavior of the description text being moved to the line with the tag.

I think what's needed is to treat @callback and @typedef differently from other tags, because these ones grab whatever text is untagged in the comment. I see you have TAGS_GROUP_HEAD already. WDYT of in those cases not pulling the text up onto the line? If it needs to be applied consistently, then an option for whether the text goes on the same line or the next line.

[hosseinmd]

Add option for this case seems good.

[hosseinmd]

We could do this with two different way,

1. Add a boolean option which start description of head tags from next line
2. add an option which giving an array of tags for start description of them from next line.
   What do you think ?

[turadg]

I'm pretty confident that head tags are the only ones you'd want to start from the next line, so I'm good with #1. I'd even suggest the the default be to exclude them from indentation and let users opt into indenting if they want. (Though I don't know why they would want to.)

I could be wrong though and there are other cases to consider. In that case #2 gives the most flexibility. But if chosen then I would request that the defaults for the array be ['@callback', '@typedef'].

If it were me I'd go with #1 and an option indentHeadTags that defaults to false.

[hosseinmd]

Description of whole block should be moved to top of block as description and other tags should be below of description.

Head tags are in top of tags and below description