docs: use same parameter names as in doc string

[rrrnld]

I realized that there is a naming mismatch in the text mismatch when looking at the docs for the polar / cartesian conversion fns: https://docs.thi.ng/umbrella/vectors/functions/cartesian.html.

I changed the references in the source code, but still saw the docs using cartesian(out, a, b?) as the function signature after generating the docs locally. I ran the following commands to regenerate the docs:

yarn clean
yarn build
yarn doc:ae
yarn doc

Is there anything else to do? I didn't find anything with rg -i 'cartesian.*?out.*?a.*?b'.

If this is a bug in typedoc I may also go the other way around and rename the function params to a and b.

[postspectacular]

@heyarne — yeah it's one of (many) TypeDoc issues, here specifically that TypeDoc ignores @param doc tags entirely in cases like this. The entire docs of the vectors package suffer from that and have been the source of much frustration, not just for users, also for myself trying to find a better solution. Some related issues (with compounding effects):

• TypeDoc (TD) is treating arrow functions as 2nd/3rd class citizens
• When using higher-order function and/or type aliases to type hint functions, it only uses the doc information (e.g. arg names) assigned to that type alias, ignoring any docstring attached in-situ.

For example, the maddN() docs completely skip/ignore the doc string which is actually present in the source.

Similar situation for most functions in the maths package, which are mostly typed using the handy FnN family of re-usable types for numeric functions. E.g. The clamp() docs at least show parts of the doc string, but the arg/param names are not the ones used in the clamp docs, but the generic ones (a, b, c) assigned to [FnN3](), which is the type alias used for hinting that function...

https://github.com/thi-ng/umbrella/blob/154c95cf9d6bab32174498ec3b5b5d87e42be7f9/packages/math/src/interval.ts#L3-L10

The only solution here would be to stop using function types altogether and then rewriting all the thousands of function headers... but I don't think that's right, and also a doc tool should not have such a major (negative) impact to force a code style, which must ignore some very useful core language features, only because the tool doesn't support them properly...

Btw. The same issue has come up several times and I do know it needs a solution, but I just don't have the energy/time to solve this. I'm grateful for any ideas though...

• 385

• 362

• 409

[postspectacular]

In any way, thank you for this PR @heyarne! Even if TypeDoc doesn't play ball, it's improving legibility!