microsoft / microsoft/tsdoc

Emitter inserts blank lines between all tags, including @param

Open
#201 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement needs design
Dominant language
TypeScript
Stars
5k
Forks
162
Avg merge
17h 24m
Merged PRs (30d)
8

Description

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

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the README example and trace the emitter path that formats parsed doc comments. Compare its output for the @param and @returns tags with the documented grouping, then add coverage showing that related tags are emitted without blank lines between them.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.