Typescript: JSDoc stripping leading whitespace in code blocks

[mjbvz]

From: https://github.com/Microsoft/vscode/issues/26415

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:

[mjbvz]

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

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

[jiayihu]

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

[mhegazy]

@sandersn, can you point @jiayihu to where this change needs to be made

[sandersn]

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.

[psyrendust]

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';
}

[sandersn]

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

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

[sandersn]

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 @psyrendust's last example, not for the oddly-indented example I just gave.

[justinmchase]

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

[mjbvz]

The original example works for me in VS Code 1.43:

[justinmchase]

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

[tulio-coppola]

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:

[erichiller]

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