[*] Links are unfollowable in generated documentation

[JeffreyPalmer]

Recent changes to the generated documentation have made links unfollowable for certain modules. For example, see: https://docs.thi.ng/umbrella/math/functions/smoothStep.html

This would normally not be a huge issue, but combined with the fact that the generated documentation also does not include the actual parameter names, I rely on this source link to find out exactly how I am supposed to be using various functions.

Ideally, the documentation would include both the correct parameter names, as well functional links to the source code.

[postspectacular]

So I haven't got a real solution yet, but have found the culprits at least. Basically, the thi.ng/api package defines various function types which are heavily used throughout all umbrella packages. In many cases these FnXXX types are used for type aliases, in interfaces or for arguments. But there're also hundreds of occurrences where they're used to simplify actual function definitions and to avoid having to type out types for all arguments, saving a lot of time & effort. The smoothStep() function is one example of this pattern:

umbrella/packages/math/src/step.ts

Lines 13 to 24 in 2065c92

	/**
	* GLSL-style smoothStep threshold function.
	*
	* @param edge - lower threshold
	* @param edge2 - upper threshold
	* @param x - test value
	* @returns 0, if `x < edge1`, 1 if `x > edge2`, else S-curve polynomial interpolation
	*/
	export const smoothStep: FnN3 = (edge, edge2, x) => {
	x = clamp01((x - edge) / (edge2 - edge));
	return (3 - 2 * x) * x * x;
	};

Here I've been using the FnN3 type alias to declare that function takes 3 numeric args and also returns a number. There're various other variations of this theme and some packages (e.g. vectors) make especially heavy use of them. These Fn types don't exist for convenience, but mainly to enforce a certain API uniformity [1] and are also needed for typing code generated functions (like 95% of the vectors package).

For whatever reason recent Typedoc versions are treating functions using these kind of declarations different than it used to (aka it breaks their docs), so maybe it's worth to also take this issue up with them! The only workaround I can see from my side is to refactor all these code sites and replace them with fully written out argument types. That'd be lot of (needless) work, is also bad for the above point made ([1]) and still wouldn't help in many cases...

IMHO what should happen is: Typedoc should have (and likely does have) access to the imported Fn types from thi.ng/api and should use that information to properly type the args in question. Right now, it completely ignores the @param doc tags provided to functions like smoothStep()... weird!

FWIW Here's a "fixed" smoothStep without the type alias:

/**
 * GLSL-style smoothStep threshold function.
 *
 * @param edge - lower threshold
 * @param edge2 - upper threshold
 * @param x - test value
 * @returns 0, if `x < edge1`, 1 if `x > edge2`, else S-curve polynomial interpolation
 */
export const smoothStep = (edge: number, edge2: number, x: number) => {
	x = clamp01((x - edge) / (edge2 - edge));
	return (3 - 2 * x) * x * x;
};

Produces:

[JeffreyPalmer]

Fascinating. Thanks for the detailed explanation.

Did you want to raise an issue in https://github.com/TypeStrong/typedoc to see if they have any thoughts?

[postspectacular]

Yeah, possibly - still want to do more testing first and see if there're any other cases, which might be related. But have to warn you already, it will take me a while and I don't know much more about Typedoc than you do yourself... so if you do have bandwidth for exploring this further or submitting an issue there, pls be my guest! :)

[postspectacular]

Just putting this here as reference, should I (or we) ever want to go forward with a custom doc gen. The ts-morph project provides a sane(r) version of working with the TS compiler API and might actually make this potential undertaking more feasible (or at least worth taking another deeper look at):

https://github.com/dsherret/ts-morph