I think Rust is something special, which is why I keep commenting on improvements I think can be made. I want to see it do well. Let me just state, I’m new to the language, but have been coding since the mainframe days (from AS/400s right up to iOS).
Some of you may have seen my original forum post Documenting a macro-based DSL. While it didn’t generate any responses, as yet, I did have someone on reddit point me to what they considered a well documented Rust macro. It made me want to drop everything and run.
While I understand that macros are a particularily thorny area to work in, I do think they are extremely cool. The problem is trying to convince others to use them when it’s difficult to know how to document their usage in a clear way, especially when some rustaceans consider the above example documentation to be a highlight.
Does anyone think it would be worthwhile investing more time in a formal documentation standard, something akin to Javadocs, and a generator that produces documentation that is easier to read? With Javadocs and other documentation systems there is a clear pattern to what you expect to find (obviously assuming developers make use of the standard). Which I personally find more readable than the existing standard documentation. It can be difficult to discern where one section or topic/function ends and another begins.
From the recent survey, we all value documentation greatly, and I think defining a more formal standard would go a long way to helping Rust’s adoption. It might even spur open source tooling improvements in this area. I may be in the minority here, but I do find the official API docs difficult to digest from a HCI perspective. Perhaps it’s my brain only, but I find the text that jumps out at me the most is the black bold text which is often “impl” and “for”, so I find it difficult to ignore that and focus on struct and trait names as well as function names.
Unfortunately there is very little advice in this area, never mind a standard. The second edition of The Rust Book seems to have dropped the section on documentation and there is just a brief mention of comments. Disappointing in light of the survey results. There is a bit of advice in the API Guidelines sitting in the nursery, but again, it’s not much beyond the suggestion of using sections with headings and appropriate linking, and a few other tips.