JSDoc stripping leading whitespace in code blocks

TypeScript Version: 2.3.2

Code

/**
 * @example
 * ```
 * if (true) {
 *     foo()
 * }
 * ```
 */
function foo() {
    return '2';
}

Expected behavior:
For the @example tag, we should return content including any leading whitespace

Actual behavior:
In this case, whitespace is stripped:

[Trace - 3:32:54 PM] Response received: quickinfo (120). Request took 2 ms. Success: true 
Result: {
    "kind": "function",
    "kindModifiers": "",
    "start": {
        "line": 9,
        "offset": 10
    },
    "end": {
        "line": 9,
        "offset": 13
    },
    "displayString": "function foo(): string",
    "documentation": "",
    "tags": [
        {
            "name": "example",
            "text": "```\nif (true) {\nfoo()\n}\n```"
        }
    ]
}

This results in incorrect rendering of the code example:

This does not happen if you have an extra newlines before the code block:

/**
 * @example
 * 
 * ```
 * if (true) {
 *     foo()
 * }
 * ```
 */
function foo() {
    return '2';
}

The issue is still there, where should I have a look in order to fix it and open a PR?

Nathan Shively-Sanders (@sandersn)

Nathan Shively-Sanders (@sandersn), can you point Jiayi Hu (@jiayihu) to where this change needs to be made

Take a look at parseTagComments, although the bug might be in the initial state when calling the function, since there's an initial indent passed in.

I'm getting a slightly different results in vscode Version 1.28.2 (1.28.2)

with newline after `@example`

/**
 * @example
 *
 * ```
 * if (true) {
 *     foo()
 * }
 * ```
 */
function foo() {
    return '2';
}

no newline after `@example`

/**
 * @example
 * ```
 * if (true) {
 *     foo()
 * }
 * ```
 */
function foo() {
    return '2';
}

no fenced code blocks

/**
 * @example
 * if (true) {
 *     foo()
 * }
 */
function foo() {
    return '2';
}

Larry Gordon (@psyrendust)

In summary, the original issue is fixed, but unfenced code blocks still squash leading white space as in Larry Gordon (@psyrendust)'s last example.

The parser doesn't know about markdown, so I suspect this is caused later in the pipeline. Needs investigation.

Larry Gordon (@psyrendust)

The problem is that the code currently only handle indentations of the form

/**
 * @example if (true) {
 *              foo()
 *          }
 */

The code starts off parsing @example's comment with the wrong indentation because it doesn't reset the indent level after parsing @example followed by newline.

Edit: the code is wrong for Larry Gordon (@psyrendust)'s last example, not for the oddly-indented example I just gave.

I see that this is closed but it appears to still be a bug in the latest release.

The original example works for me in VS Code 1.43:

False alarm. It wasn't working for me I swear, but just trying it again its now fine... Please ignore.

A related issue still occurring on version 1.44.0

The original example works:

But if you use the <caption> tag on the @example it breaks again and trims the whitespaces:

Doubling what @tulio-coppola said, <caption> seems to break things.
<caption> requires an initial indentation, whereas, without <caption> (second example below) no initial indentation is required

Example:

/**
 * Create a new type which has the properties of `Base` that match `Condition`
 * 
 * @example <caption>This example extracts properties of `foo` that have a value type of `string`</caption>
 *          // `fooT` is now { a: string, d: string }
 *          // `fooKT` is now ` 'a' | 'd' `
 *          interface foo {
 *              a: string;
 *              b: number;
 *              c: string[];
 *              d: string;
 *          }
 *          type fooT = SubType<foo, string>;
 *          type fooKT = keyof fooT ;
 * @example
 * interface foo {
 *      prop: string;
 * }
 */
export type SubType<Base, Condition> =
    Pick<Base, AllowedNames<Base, Condition>>;

results in:

This is 1.45.1 on Windows

This issue is still present in the latest version of TS and VSCode.

Please open a new issue; this one has been closed a long time.

Navigation Menu

Repository navigation

JSDoc stripping leading whitespace in code blocks #15749

with newline after `@example`

no newline after `@example`

no fenced code blocks

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

JSDoc stripping leading whitespace in code blocks #15749

Description

Activity

mjbvz commented on May 10, 2017

jiayihu commented on Jul 10, 2018

mhegazy commented on Jul 10, 2018

sandersn commented on Jul 10, 2018

psyrendust commented on Oct 31, 2018

with newline after @example

no newline after @example

no fenced code blocks

sandersn commented on Mar 13, 2019

sandersn commented on Apr 8, 2019

justinmchase commented on Feb 26, 2020

mjbvz commented on Feb 26, 2020

justinmchase commented on Feb 26, 2020

tuliocoppola commented on May 11, 2020

erichiller commented on Jun 8, 2020

davwheat commented on May 1, 2021

sandersn commented on May 4, 2021

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

with newline after `@example`

no newline after `@example`