4 ms·

Why does embedding the documentation into the source code make it weaker? The author can put as much or as little effort into the documentation as they want eit

• lifthrasiir 2y ago
  A documentation is written for particular audiences, not always but typically users. And a user-directed documentation is largely a hindrance for whoever is actually updating a source code adjacent to that documentation, because it acts like a boilerplate template. An embedded documentation does make the absence of documentation obvious and helps towards the completeness, but not without a compromise. Ideally it should then be reordered and further elaborated externally so that it can be maximally useful. Rust has a good documentation but the general lack of such manipulation makes it often hard to navigate. For example `Vec` [1] has a lot of inherent methods with two separate orderings, where one is alphabetical in the sidebar and another is the declaration order, but none of them are actually logical and will benefit from reordering in general. Of course Rust folks are aware of this issue and have put a lengthy introduction with most important methods for each category, but that's less flexible and prone to future updates. [1] https://doc.rust-lang.org/stable/std/vec/struct.Vec.html https://doc.rust-lang.org/stable/std/vec/struct.Vec.html
  • db48x 2y ago
    I’m not so sure that the order of methods matters very much in most cases. In Rust you can at least present them in any order you like, or you can use the module or trait documentation to explain how the order matters.