Emitter inserts blank lines between all tags, including @param

[iansan5653]

According to the readme, @param and @returns should go together in a group like so:

  /**
   * Returns the average of two numbers.
   *
   * @remarks
   * This method is part of the {@link core-library#Statistics | Statistics subsystem}.
   *
   * @param x - The first input number
   * @param y - The second input number
   * @returns The arithmetic mean of `x` and `y`
   *
   * @beta
   */

When this comment is parsed and emitted by the emitter, blank lines are inserted between all the tags, including the @param and @returns tag:

/**
 * Returns the average of two numbers.
 *
 * @remarks
 *
 * This method is part of the {@link core-library#Statistics | Statistics subsystem}.
 *
 * @param x - The first input number
 *
 * @param y - The second input number
 *
 * @returns The arithmetic mean of `x` and `y`
 *
 * @beta
 */

These should be output as a group (or at least have an option to output them as a group).

[octogonz]

Blocks contain a DocSection that is an array of DocParagraph objects, which are delimited by blank lines (because their content may span multiple lines). Adding an extra line is the simplest way to handle this.

For example, if the emitter instead skipped as few lines as possible, then this counterexample comes out a little weird:

/**
 * Returns the average of two numbers.
 * @remarks
 * This method is part of the {@link core-library#Statistics | Statistics subsystem}.
 * @param x - The first input number
 * has an entire paragraph of text.
 * 
 * Followed by another paragraph
 * that spans multiple lines
 * as in this example.
 * @param y - The second input number
 * @returns The arithmetic mean of `x` and `y`
 * @beta
 */

Thus, to get this right, we may need to introduce some subjective heuristics about when it looks best to skip a line.

[octogonz]

Both your issues #200 and #201 seek to improve the aesthetic appearance of the TSDocEmitter.renderComment() API. Perhaps they could be tackled together.

At the time when I implemented TSDocEmitter.renderComment(), I only needed it to serialize comments for API Extractor's .api.json intermediary data files. Humans generally don't look at this content. Thus, I didn't need to put much effort into aesthetics. So maybe it's time to improve it. :-)

What are you planning to use this for?

[iansan5653]

Thanks for the info. Maybe we should introduce some notion of tags that typically form a group? For example, all @param tags (and maybe @returns) should be grouped together. All of the modifier tags should probably be grouped as well since they don't have any content.

As for what I'm planning to use this for - I'm working on a simple VSCode extension that formats TSDoc comments - currently there's nothing out there for that and this is an almost-complete implementation so it makes sense to work off of this API.

[octogonz]

As for what I'm planning to use this for - I'm working on a simple VSCode extension that formats TSDoc comments - currently there's nothing out there for that and this is an almost-complete implementation so it makes sense to work off of this API.

Awesome! Maybe it could also be used to format the docs as @maasha suggested in #198.

[octogonz]

Separate from this issue, we should determine a normalized form for TSDoc comments. This can serve as a spec for any rewriting that is (optionally) performed by TSDocEmitter.renderComment(). We can reuse RFC #13 for this discussion.