Can't get JsDocs directly from a VariableDeclaration

[JoshuaKGoldberg]

/**
 * First
 */
const firstVariable = true,
    /**
     * Second
     */
    secondVariable = false;

import { getJsDoc } from "tsutils";

// Edit: not visitVariableStatement(node: VariableStatement)
function visitVariableDeclaration(node: VariableDeclaration) {
    // Blank
    getJsDoc(node);

    // Always ["First"]
    getJsDoc(node.parent);
}

Expected:

Calling getJsDoc on a VariableStatement should retrieve the docs for the node, even if they're also the docs for the containing VariableDeclarationList.

Actual:

Only ever gets the docs for the VariableDeclarationList.

[ajafff]

I think you mixed up VariableStatement and VariableDeclarationList in your example. VariableDeclarationList never has any JSDoc, because it is located on the VariableStatement.

This function is not intended to find the JSDoc on any parent node. It's just a thin wrapper to make the internal property Node.jsDoc available to use in your program. TypeScript never parses JSDoc on VariableDeclaration or VariableDeclarationList. You need to take care of passing the correct node to the function.

If there is the need for a function that retrieves JSDoc for a node the way TypeScript does, I can probably add that on top.

[JoshuaKGoldberg]

Yes and yes. The context is TSLint's completed-docs function.

[ajafff]

@JoshuaKGoldberg what would the ideal API look like?

You throw in any Node / (Named)Declaration and get back the JSDoc TypeScript would use? Should it automatically search for JSDoc on the opposite property accessor?

[JoshuaKGoldberg]

IMO yes, but with the caveat that it only looks at the single file (no class inheritance checks or the like). Other than that get/set edge case, and parsing through variable statement/declaration/declaration lists, I can't think of other edge cases.