Removing/renaming type aliases to improve readability of documentation

[ElectricCoffee]

Sometimes reading the piston documentation is a bit of an uphill battle, just today this happened:

I needed to see the types I needed to put into a square to make a wrapper function, so I see that graphics::rectangle::square has the signature square(x: Scalar, y: Scalar, size: Scalar) -> Rectangle.

First thought? "What on earth is a Scalar?" ... It's just an f64. Why not just write that?

Arguably "Scalar" is a less helpful type name to the programmer at first glance than the familiar "f64", especially since nothing special is done to the type.

But fair enough.

I then notice that the returned Rectangle is not a rectangle::Rectangle at all, but a types::Rectangle, which is an alias for a [f64; 4]... Why does it have the same name as an entirely different type? That's incredibly unhelpful.

Simply making the function signature square(x: f64, y: f64, size: f64) -> [f64; 4] tells me loads more about what the function is, than hiding it all behind several layers of indirection; heck (:snake:), calling [f64; 4] "Rect" would've been more helpful to give a visual distinction from the other "Rectangle" type within the library.

I don't know, it's these small things that sometimes makes me pull my hair out when trying to use a library.

I feel that removing unnecessary type aliases would dramatically increase the readability of the docs, at least for things like primitive numeric types.

[bvssvni]

The type alias for primitive types is meant for recompilation for f32 targets.