Hi, sorry if this is the wrong place to post this, but there are some things that I think nalgebra could do better in terms of documentation.
Take for example the documentation for a Ray. This is created using an ncollide3 Point, which is a nalgebra Point3, which is a nalgebra Point. Someone experienced with nalgebra who is seeking to construct a Point might notice the new methods on the side, which may be used to construct the Point, but someone inexperienced with the library might notice that a Point itself has a public field coords which is a VectorN<N, D> which is a MatrixMN<N, D, U1>, etc, etc, and go on a long search to construct something that should be fairly straightforward, a point in 3d space.
Part of the blame here lies in how Rust generates documentation, but part of it also lies in how nalgebra is organised. Is having a long chain of type definitions really better than just having a both Point2, and Point3 structs, with traits implemented for both?
I really want to like and use nalgebra frequently, but I also don’t enjoy how long it takes to find what I’m looking for in the documentation.
Hi, thank you for your feedback! This is a good place for this kind of discussion.
I am currently working on improving the documentation by adding more # Example and # See also sections (like this) to all methods to facilitate the discovery of features. For your specific example, I believe adding an # Example of construction of a Ray under the documentation of Ray::new would make the construction of the required arguments clear.
Adding this kind of documentation takes a lot of time though so it might take a while before it is exhaustive. Right now I am focusing on nalgebra.
Having tried the trait-based approach before the current design, it is actually more difficult to use since you end up having to search what trait you have to import to get what feature. In addition, this would make interaction with the rest of the library very difficult, for example, things like operator overloading will quickly be impossible to implement due to restriction on blanket impls.
In retrospect, I think I was a little too harsh in this post. I think that if rustdoc documented inherited functions from type definitions the same way it did derefs that would help a lot. Is these a github issue for missing examples for common structs?
Yeah, to me this is the biggest issue with nalgebra documentation at the moment. If displaying these inherited functions was fixed I think usability would improve substantially.
There is none because the list would be extremely long since everything needs good examples. Right now I’m focusing on nalgebra (and won’t be done for at least a couple of months), but if you are interested in contributing on this, you may add some doc-tests to the structs you use from ncollide for example!