postspectacular
commented
2 years ago 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:
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
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.