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

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.)

[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]

Add option for this case seems good.