lovr.math.mat4() / mat4:set doesn't document all variants

[nevyn]

For example. you can lovr.math.mat4(lovr.headset.getPose(...)), which is not obvious because the documentation doesn't mention an overload of set() which takes x, y, z, a, ax, ay, az.

[bjornbytes]

This is supposedly covered by Mat4:set containing the Mat4:set(position, orientation) variant. But it's confusing because in some places the docs document parameters as numbers and you can implicitly use vectors, but in other places (like here) it's the other way around where the vectors are documented and numbers are implicitly valid.

I guess there isn't a consistent convention in place, which is a source of confusion. Ideas:

• Document vector-y parameters using vector objects, make numbers implicit (documenting it somewhere).
• Document vector-y parameters with numbers, make vectors implicit.
• Be explicit and always provide both the number and vector variants. The only issue here is the combinatorial explosion of variants (lovr.graphics.box would have something like 2 * (2 * 2 * 2 + 1) variants), which I think would make the docs more difficult to understand.
• Build a system for metatypes. A vec3 metatype would have its own page and describe that vec3 arguments can be provided as a temporary/permanent Vec3 object or 3 numbers (maybe naming this one vec3 is confusing, but it could be named something else like number3 or point3 or v3 or something...). Any place where the function parameters behave this way could link to the page. Other possibilities for metatypes would be pose, transform, file (filename vs. Blob), style (DrawStyle vs. Material), data (string vs Blob?), and variant (all the data types that can be pushed to events/channels).

Thoughts?

[nevyn]

ahhh. I didn't know that was universal; I've only noticed here and there that vec3/mat4/quat are valid where the docs mention the flat values.

My personal take (but I feel like this is very much a matter of taste) is that I strongly prefer the shorter signatures with explicit higher types (e g position, orientation over x, y, z, a, ax, ay, az). Coming from a strong OO background, if I had built lovr from scratch, I probably wouldn't have had the numbers variants at all, at least not if the vec lib is fast enough (which I think it is with the pooling?)

So I'd vote for A. If I did A, I think I would also actually always mention "you can also send in x, y and z as separate values" in every location in the docs where a vector is taken, just so it doesn't depend on you having carefully read the "vectors" page (but without making it a separate type variant; just mentioning it in the parameter description text). But that's just me :)

I think lovr's documentation would be considerably improved if we found a nice generic solution here; this implicitness has been confusing me from the start. But for this specific issue, I'd be happy just being super explicit in the vector classes's set functions, since those are so important :)

[KelseyHigham]

How do the number/vector variants work, and where are they specified? Would it make sense for the documentation to imitate the structure of the source code, or does the source code also have a combinatorial explosion of variants?

[bjornbytes]

In the source code, lovr usually does things like readmat4(arg2), readquat(arg1). Those helper functions handle the different supported variants.

I do think after thinking about it more I lean towards documenting it using the metatype approach, like saying "arg 2 is a $transform" and having that link to a page that explains the different ways you can provide one. It matches the source and is easier to maintain/read in the long run.

[eigenbom]

Following up on https://github.com/bjornbytes/lovr-docs/issues/99#issue-1508759406 ...

As a new user it wasn't too clear how to use these functions. I had to grep the lovr source code for examples. In hindsight I don't think we need to list all variants, but a tooltip or breakout box on each page describing how (in general) the expanded forms work would be nice.

[bjornbytes]

Here's a crude mockup of my idea for a way to document all the variants, make it easy to see them all at a glance, and avoid scrolling through tons of similar-looking variants to find the one you want:

There's an initial listing of all the variants in some kind of list/table. Each one can be selected (in this example, the last one is selected, so it's brighter/underlined). The arguments/returns table only shows the details for the variant that's currently selected.

It removes the ability to scroll through them all (and maybe compare differences?), but adds the ability to see all of them at once and quickly switch between them.

[eigenbom]

Thx! That's an improvement, I appreciate seeing all the function declarations like this. Perhaps you could put the original/simple version up the top and list in increasing order of complexity.

Pass:plane(transform, style, columns, rows)
...
Pass:plane(x, y, z, w, h, angle, ...)

[bjornbytes]

Ok, everything that takes a Vec3/Quat/Mat4 now explicitly lists numeric, vector, and mat4 variants. It's not quite the full expansion of all the combinations, but it's comprehensive enough that it shouldn't be confusing anymore.

[eigenbom]

Looks great to me :)