Docstrings don't show correctly

[nkint]

Hi :) not sure if opening an issue is the right thing, if a general discussion could fit better I'm happy to move there.

I'm noticing that docstrings not always show in the correct way, is it a problem in my vscode settings?

In this screenshot:

I'm expecting to see:

Multiplies 3x3 matrix m with 3D vector v. Supports in-place...

In the same way in this screenshot:

I see:

An object that represents a number of any kind. All JavaScript numbers are 64-bit floating-point numbers.

Does it make sense? Am I the only one having this problem?

p.s. I know that in the first screenshot the order of arguments are wrong. The documentation of the code in this repository is super well done, it's a pity I'm not seeing it 😥

[postspectacular]

Ciao @nkint - welcome back & nice to see you back here!!! 👋 You're not the only one struggling with this, and even though I think I know why/when this issue/behavior occurs, I still don't know a practical solution to counteract it! Filing an TS issue upstream might be required.

As far as I can tell, the docs are not being displayed for any function which uses a type alias to simplify (or enforce) its signature.

For example, the mulV33() function has this type declaration in its related mulv.d.ts file:

import type { MatOpMV } from "./api.js";

/**
 * Multiplies 3x3 matrix `m` with 3D vector `v`. Supports in-place
 * modification, i.e. if `out === v`.
 *
 * @param out -
 * @param m -
 * @param v -
 */
export declare const mulV33: MatOpMV;

In contrast, the scaleWithCenter23() function (same package) has a full (without type aliases) signature and therefore properly triggers doc strings on hover:

/**
 * Computes a 2x3 matrix representing a scale operation with origin `p`
 * and writes result to `out`.
 *
 * @param out -
 * @param m -
 */
export declare const scaleWithCenter23: (m: Mat | null, p: ReadonlyVec, s: number | ReadonlyVec) => import("@thi.ng/vectors").Vec;

I don't know/understand why the TS language server treats these cases differently and doesn't show the docstring for the first one, esp. since it obviously has all the proper typing info available...

I tried to look into that a few years back already, but didn't find anything super relevant in the TypeScript issues. Maybe, if you have time for it, you could try submitting an issue/question there, since this isn't just an issue related to umbrella packages...

[nkint]

hi karsten! good to know that it's a common issue... thanks for the detailed answer, as usual!

[postspectacular]

Thanks, @nkint! Please let me know if you're going to submit an issue for TypeScript about this. Else I will add it to my to-do list...

Pa. Not just in this case, but also with other related tooling (e.g. TSDoc), there seems to be a general attitude of treating arrow functions as obscure/special cases. Lucky for all the projects here which almost exclusively use arrow functions! 😩