Single newlines in @param blocks are interpreted as linebreaks in generated markdown

[cywang90]

What package is the bug related to?

docusaurus-plugin-typedoc

Describe the issue

Single newline characters in @param blocks are preserved in the generated markdown files and are even converted to <br/> tags when parametersFormat: 'table' is used.

For example, take the following documentation:

/**
 * @param param1 This is a parameter documentation with a newline after this sentence.
 * This sentence is on a new line.
 */
 function foo(param1: number): void { }

It gets translated into the following markdown:

• **param1**: `number`

This is a parameter documentation with a newline after this sentence.
This sentence is on a new line.

This is unexpected but somewhat okay since single newlines are still treated as spaces in markdown.

However, when formatting parameters into a table, the following markdown is generated:

| Parameter | Type | Description |
| :------ | :------ | :------ |
| `param1` | `number` | This is a parameter documentation with a newline after this sentence.<br />This sentence is on a new line. |

Now there is an undesired forced linebreak where the single newline character used to be.

TypeDoc configuration

typedoc: v0.25.13 typedoc-plugin-markdown: v4.0.1 docusaurus-plugin-typedoc: v1.0.1

Options (passed to docusaurus-plugin-typedoc):

{
  excludePrivate: true,
  parametersFormat: 'table' // or 'list'
}

Expected behavior

Single newlines in @param blocks should be interpreted as a space instead of a linebreak. They should never be converted to <br /> tags in markdown and probably should always be converted to a space instead of being preserved as a newline character.

[KillyMXI]

I experience a related issue with parametersFormat: 'table'. I may open a separate issue later, if necessary. I actually use paragraphs in doc strings extensively (that is, lines of text separated by empty line or two line-breaks, after you remove the comment markup). And I observe nearly all markdown tables broken, because I get unexpected newlines before <br />. Expectation - one (maybe two) <br /> tags and no \n inside tables, when paragraphs are found.

And something is wrong about abbreviated text for index table. Expectation is to have full (or at least with ellipsis) first paragraph without \n in the output. In reality, it can produce first line until line-break in the input, can output unexpected line-break after first paragraph, can ignore the only description paragraph before @param.

[tgreyuk]

Thank you. Fixed in typedoc-plugin-markdown@4.0.2.

@cywang90 you are absolutely correct a soft line should not result in a line break.

@KillyMXI Your issue with the superfluous should also be fixed. Please do a raise a separate issue regarding index tables.

Handling how to process comments inside the table is actually a bit complex. We basically cannot have any markdown blocks rendered in the table, so the solution to this bug is to first normalize line breaks and then parse markdown block tags to html. Previouslly we were just converting new lines to
which is not correct.

[cywang90]

@tgreyuk Thanks for the quick fix. Just re-built my docs using v4.0.2 and can confirm my issue was fixed.