A more formal documentation standard? (incl.macros)

[rayascott]

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.

[killercup]

@rayascott

Does anyone think it would be worthwhile investing more time in a formal documentation standard

Yes

[steveklabnik]

@rayascott

It made me want to drop everything and run.

So, this isn't due to someone writing docs. This is how rustdoc prints out docs for any macro. It may not be the best way. We're generally open to suggestion!

@rayascott

The second edition of The Rust Book seems to have dropped the section on documentation

It was largely moved into the documentation for Rustdoc, since we have that now.

@rayascott

Which I personally find more readable than the existing standard documentation.

It seems to me like you're mostly concerned with the output of rustdoc, not the actual form of the docs themselves. We can change and tweak this without needing to define a ton of semantic stuff. I could also be wrong, but most of you comments feel related to presentation to me.

@rayascott

Does anyone think it would be worthwhile investing more time in a formal documentation standard, something akin to Javadocs,

I personally don't. I find that they mostly encourage people to write poor docs, in that they end up being largely redundant. The lighter-weight you make writing docs, the more likely they are to be written.

That being said;

@rayascott

a generator that produces documentation that is easier to read?

I don't think rustdoc is perfect. Expect some news on this front next week or maybe the week after

[rayascott]

Thanks for the detailed reply. I think my concern about the output is secondary to a more codified formatting standard. As you say, some documentation can be fairly redundant and it’s largly left to the discretion of the author not to bore the reader.

Certainly when it comes to documenting function parameters it can be a bit pointless to describe the age argument being passed to person struct which is what Javadoc’s promote with the @param keyword.

I know my macro example is extreme, but particularly for non-macro function returns I find a gap, because unlike Swift where the return arguments (optionally) are named (imagine if function parameters weren’t named), with Rust that isn’t true. This is where I miss some sort of rigor with regard to clear documentation.

Clarity over obscurity I think would be a worthy endeavour to promote with regard to rustaceans documenting their code. The best we can do is hope

[carols10cents]

@rayascott

The second edition of The Rust Book seems to have dropped the section on documentation

There is also this section as part of the publishing to crates.io section, but yes, as steve noted, the nitty gritty details of rustdoc deserved their own resource.