search

dimforge / nalgebra

Linear algebra library for Rust.
https://nalgebra.org
Apache License 2.0
4.05k stars 485 forks source link

Improve method discoverability #370

Open sebcrozet opened 6 years ago

sebcrozet commented 6 years ago

Because of the complexity of the rustdoc-generated documentation, it is often difficult to find the right method to do something in nalgebra. This issue aims to collect feedback from user that struggled finding how to do something.

Collecting those feedbacks will help designing a "Beginner's guide" on the nalgebra website.

sebcrozet commented 6 years ago

Here are some pain points identified by @icefoxen :

See also https://wiki.alopex.li/LD42Postmortem for a feeback.

arturoc commented 6 years ago

Something i only discovered recently is that VectorX::*_axis() returns a unit, before i always was using Unit::new_unchecked(Vector3::x()) which is super verbose

Also i always have to look up and not sure if i'm even using the best solution is how to go from a Matrix4x4 to a Matrix3x3

icefoxen commented 6 years ago

I appreciate the shout-out, but I'm afraid I don't really have a coherent set of suggestions of how to make things better, or even really a good handle on Why This Is So Hard. The best I can say right now is that rustdoc isn't up to the task of explaining how the heck to actually make nalgebra work and that makes searching the API docs way harder than it should be.

Part of this is because I'm also basically singularly focused on computer graphics and fairly simple physics, and so all the Cool Stuff like BLAS functions or SVD (or even really simple but never-useful-for-computer-graphics stuff like Matrix::upper_triangle()) is worse than useless, it's noise that has to be filtered out. However, not everyone has this use case; if someone wants to use nalgebra for simulation or data processing work then it's useful to have functions for every gnarly little math edge-case possible.

Maybe we can start by coming up with a basic cheat-sheet of Useful Vector And Matrix Methods We Actually Care About For Video Games, see what it looks like, and think about what to do with it?

sebcrozet commented 6 years ago

Thank you for your feedbacks so far @icefoxen and @arturoc .

Another addition: better documentation of matrix construction methods, depending on their dimensions (small, dynamically-sized matrices, etc.) This was proposed in the third point of this forum post.

purpleposeidon commented 6 years ago

cargo doc just isn't good enough. What about literate programming? Or rather a slightly modified version that skips implementation detail. I suspect skimming nalgebra's source up front may be best.