For instance reading std.hash_map.HashMap the documentation comment in the actual code looks great:
/// General purpose hash table.
/// No order is guaranteed and any modification invalidates live iterators.
/// It provides fast operations (lookup, insertion, deletion) with quite high
/// load factors (up to 80% by default) for low memory usage.
/// For a hash map that can be initialized directly that does not store an Allocator
/// field, see `HashMapUnmanaged`.
/// If iterating over the table entries is a strong usecase and needs to be fast,
/// prefer the alternative `std.ArrayHashMap`.
/// Context must be a struct type with two member functions:
/// hash(self, K) u64
/// eql(self, K, K) bool
/// Adapted variants of many functions are provided. These variants
/// take a pseudo key instead of a key. Their context must have the functions:
/// hash(self, PseudoKey) u64
/// eql(self, PseudoKey, K) bool
But when looking at the website it doesn’t translate softline breaks to linebreaks resulting in ugly formatting. What should change, autodoc or the documentation comment?
It is just the Markdown format, the authors of the docs could do a better job in ensuring the rendered docs are readable.
Its just not priority, I expect it will be as 1.0 nears.
Something I do, and I think Andrew does too, is to just use the std source. My editor has decent navigation, but that’s not required, knowing your way around standard terminal tools is just as effective for navigation.
That’s not the best way to solve it: on the web, the viewport width vary, so the browser should figure out appropriate line breaks, which depend on whether you are viewing the docs on mobile or desktop. But, yeah, there needs to be max-width: 80ch; somewhere in the CSS.
When doc comments are processed as Markdown by the docs processor, they should be written as Markdown (which is perfectly readable plain text). In code, they should be formatted to a limited width for reading in source as well. But they do need to have the empty lines between paragraphs.
The quoted example is just manual plain text, yielding the poor results. Clearly, docs are currently, and arguably appropriately, low priority, But at some point a comprehensive editing pass will need to take place to fix rendering, layout, spelling, grammar, voice, etc. Andrew has previously posted a position that any PRs addressing such issues need to be comprehensive, and at least for spelling, prophylactic (meaning there is a process in place to prevent such errors from being introduced into mainline going forward).
Creating good docs is a churn generator for code. There is a tension there. There’s an argument to be made that documentation should not be generated from source, but rather there should be a doc tooling workflow that checks documentation against the code, so that documentation can be developed and maintained by professionals separately and parallel to the code.
