More api documentation conventions

[steveklabnik]

rendered

[updated to link to final rendered version]

[nrc]

Is quoting for emphasis something that people do deliberately? I thought it was a mistake. Maybe an english/american thing. Anyway, can we recommend using markdown punctuation for emphasis? Or are we targeting an ascii world? I.e., *foo*. And then just quotes for quoting?

[steveklabnik]

Yes, it is something that's done deliberately, though I am not aware if it's a regionalism or not.

I've often seemed bolding used when showing off a term for the first time, or to highlight things for other reasons. Maybe this is too specific, though. Right now, all the docs use quoting for emphasis, and use bold very sparingly.

[jimmycuadra]

Anecdotally, I can't recall ever seeing single quotes used for emphasis except in Rust documentation. I don't think it's standard or common.

[codyps]

for what it's worth, asciidoc uses single quotes to emit emphasized (italicized and differently colored) text. Perhaps rustdoc simply needs to use a similar rule & emphasize single quoted text? Or just convert the existing single-quote-to-emphasize into some other markup that actually applies an emphasis style?

[cmbrandenburg]

Always worth a laugh: the blog of unnecessary quotation marks.

[jimmycuadra]

I originally used the section headings (e.g. examples, failures, etc.) in my docs but stopped doing it because of how hard it is to read with the current styling of rustdoc pages. The headlines are way too large, and the underline beneath them makes it very hard to see the separations between functions, as the eye is drawn to the underline instead. I'm not sure whether or not it makes sense to take the current usability issues of rustdoc into account when considering this RFC. The idea on its own is good, but I'd hesitate to make the recommendation until rustdoc is easier to read.

[zetok]

You got that one wrong.

It should be preferable to avoid line comments, and use block comments whenever possible.

Case: line comments aren't that easy to work with for blind people, like block comments are.
#1373 (comment)

Also note that block comments should be

/*
    Some
    multiline
    comment.
*/

with no unnecessary asterisks.

[steveklabnik]

This particular convention has already been in place for years, and is in the original RFC. (I am interested in the a18n bit though)

[zetok]

This particular convention has already been in place for years, and is in the original RFC.

Yes, I know. Just because something has been in place "for years" doesn't mean that it's right.

I just wanted to highlight that this RFC makes same mistake as the original one – hopefully there'll be interest to make corrections :)

[starkat99]

I agree, accessibility should be enough motivation to change the standard here.

[GuillaumeGomez]

Also note that block comments should be

/*
    Some
    multiline
    comment.
*/

with no unnecessary asterisks.

I disagree. I guess it's a personal opinion but I really don't like this writing.

/*
 * Some
 * multiline
 * comment.
 */

Is more pleasant to read. Or:

// Some
// multiline
// comment

(which is my favourite).

[eternaleye]

@GuillaumeGomez That just revives the exact reason @camlorn gave for preferring block comments for a11y reasons - specifically, that screen readers then pepper their output with meaningless noise, obscuring the comment itself.

It may be more pleasant to read for you, but I find the two about equal, and for people with a11y concerns your proposal is just as bad as line comments.

[Centril]

@steveklabnik As discussed in IRC, I think the part about American English should be clarified so that it states that this is preferred/required in the standard library (and cargo) and not in community libraries.

[robinst]

I think referring to ` as "backticks" is more common than "graves", and also matches the terminology that both Markdown and CommonMark use.

[GuillaumeGomez]

Agreed.

[nixpulvis]

Where exactly do you draw the line for lengthy?

[GuillaumeGomez]

I guess it'll be "on case".

[peschkaj]

"Lengthy" would be, for me, when absolute correctness gets in the way of communicating clearly. This goes along with why we frequently unwrap() in documentation, even though we all why we shouldn't do it in production.

[nikomatsakis]

Wait, would you expect to ever write bounds? I would not.

[ahicks92]

Sorry, but I can't work out how to reply to inline comments to the diff. I'm not actually sure that's possible, but GitHub's interface has enough accessibility problems that I'm not sure.

As long as this remains a recommendation and I'm free to ignore it in my own projects, I'm more indifferent than you'd think. If I thought we could make the guideline say use block comments, then I'd be all over that. But people are going to just use line comments all over anyway. If the response to suggesting line comments for documentation is more than borderline in favor, I'm not going to come out of the woodwork later and try to make us change it. I do similar ignoring on Python's PEP8.

I'm in favor of removing it or even changing it to block commenting, but I thought it was worth clarifying that I'm not going to be unreasonable about us having it. My issue with the other one is that it essentially wanted to force it at a compiler level, which means that not only is it a guideline, it's one I can't just ignore for justified reasons in personal projects. I might end up contributing to the standard library and would be thrilled if it started using block comments as this would involve writing documentation, but I am realistic enough to realize that line comments are overwhelmingly preferred for this purpose and that I have rather unique preferences. Suffice it to say my commenting style is inconsistent. There are rules, but I'm not sure I could explain them.

Also, as a sidenote, I'm glad that people actually remember my comments. The responses to "Hi I'm a blind programmer and here are my problems" in this community have been more positive than every other time I've tried to have conversations about accessibility with people who aren't the devs of my screen reader. Usually you're just completely ignored as a minority.

[eternaleye]

@camlorn Regarding replies to comments on diffs, GitHub encloses diff-comment threads in a div with the discussion-item class, which contains (near the end, and several layers of nesting inwards) a button with the text "Add a line note" and the class js-toggle-inline-comment-form. That button enables a comment editor for that thread, and it may be possible to have a userscript that iterates over the page and enables all such editors.

If that doesn't work, it may also be possible to reply to the appropriate email and have it be placed correctly, but I'm not especially optimistic.

[nikomatsakis]

Nit: I would recommend [Rust website][], since this avoids ambiguity in the case of two consecutive comments (like, [Rust][] [website][]).

One question that I had was whether this was intentionally recommending against using a shortened thunk like [Rust website][rw]? (I don't think we should take a stance about that; let people decide for themselves based on how long the link text is.)

[steveklabnik]

I personally feel that it looks much uglier, but you're right that it can remove ambiguity. However, I don't think that putting two links side by side like that is generally a good idea, because then it looks visually ambiguous when rendered; it all looks like one big link.

And yeah, my intention wasn't to ever say never. I'll modify it to make this clearer.

[steveklabnik]

I've pushed an update to the structure of the RFC, though it's not quite 100% done yet. Rather than make the whole RFC a new text, I'm going to make the full text an appendix, and only include my changes in the body itself. This will make it more clear what's up for discussion and what isn't.

@camlorn #1574 (comment) : Yes, this is largely intended to the project itself, as well as giving projects a starting place to work. While I do care a lot about the accessibility case, I'd be interested in hearing more generally across a variety of screenreaders, rather than hastily changing a ton of styles because of one instance of difficulty. Thanks for chiming in here and in the other threads I've seen you in, though: I've done a little bit of accessability work on Rustdoc's output, but we have a long way to go...

@Centril #1574 (comment): absolutely, this should be taken care of in the commit I just pushed

@jimmycuadra #1574 (comment) I hear you, but changing Rustdoc's output is a different thing. I'd rather fix that issue than change semantic conventions because the current output is less than than stellar.

[robinst]

grave → backtick here too?

[carols10cents]

I just got a great review on some doc changes, and reading your comments gave me the sheepish feeling that there were some style guides about docs that I should have read. 🐑 😳

I found this, and it does contain some of the suggestions you made (like a one-line summary at the beginning) but I think it could also use:

• When referring to functions, include the ()
• Module-level documentation should provide a broad overview; details should be in the struct/function/trait/etc documentation
• Strive to make code examples run with out warnings?? I'm not sure about this one; the stdlib seems inconsistent to me and I'm not sure if this is enforced.
• I think it'd be worth saying, though it sounds super obvious, that code examples should follow the stdlib coding style? Maybe?

[steveklabnik]

Okay! Thank you for the delay here, everyone.

I believe I have addressed most/all of the comments here, but in different ways. Some of them have been updated directly, others have not, for a few reasons.

Basically, it's not my intention with this RFC to re-litigate what was decided in RFC 505. As such, this RFC is now broken out: the contents of the RFC are just the conventions that I'm proposing we add or tweak, and then the full text of RFC 505 + this RFC is added into an appendix. Some of the comments were about stuff that was in RFC 505, and that's out of scope of this RFC.

I would like to specifically call out the block comments vs line comments thing with a personal note. I do not want to change this in this RFC, but I also don't want this to be taken as not caring about the accessibility issue. However, I think that the accessibility issue needs to be dealt with more holistically: is it just this one particular screen reader that has issues, or is it many of them? Is there a way we could improve that software to deal with this particular issue, such that it would help everyone? Even if we did decree that this needed to change in the standard library today, as it is a years-long convention, there is a lot of Rust code that would still be using this style. I think accessibility improvements would be great, generally, but also don't want to block the rest of this RFC on this issue, specifically. And since the proposed changes here don't make the situation worse, I feel it's okay to not address them at this particular moment.

A few others were about something we can't really change right now: rustdoc. I would prefer to not have to manually link, but until some hero goes and figures out a markdown extension to auto link types and implements it in Rustdoc, it's not realistic, so it is what it is, for now.

Whew! So with all of that, please re-review the actual Detailed Description. Thank you everyone!

[GuillaumeGomez]

"if there is a some small amount"?

[steveklabnik]

Nope, it would be "if there is some small amount" or "if there is a small amount" 😄

[GuillaumeGomez]

Damn! Too much "some"! 😆

[jbcden]

Should the # be in the middle of this line? If it is there to give an example of headers, we should do something to make it stand out more.

[GuillaumeGomez]

Right, a rewording might be needed.

[steveklabnik]

Hear ye, hear ye! The nanescent docs team has decided to move this RFC into its final comment period.

[wycats]

@steveklabnik More consistency for the win!

[joshtriplett]

I don't think code documentation conventions should recommend putting punctuation inside the quotes unless the punctuation itself is part of the quote. Quoting the Jargon File, chapter 5, "Hacker Writing Style":

This is incorrect according to standard American usage (which would put the continuation commas and the final period inside the string quotes); however, it is counter-intuitive to hackers to mutilate literal strings with characters that don't belong in them.'

This case will come up often in documentation, and a style guideline should not make a recommendation that on balance will reduce precision in favor of an arbitrary English formatting/typesetting convention that isn't even universal in English text. (Convention varies: as I understand it, some style conventions for British English also put the punctuation outside the quotes.)

I realize that a style guide is the ultimate example of a bikeshed topic, and for the vast majority of items an arbitrary convention for consistency improves on having no convention at all. But in this particular case, I think this guideline does more harm than good.

[brson]

lgtm. <3 good docs

[steveklabnik]

Hooray! The docs team, alongside the core team, has decided to accept this RFC.

There were some questions about a few points, and we decided to remove them all. You can see this in the last three commits I pushed to this branch last week.

Thank you everyone! I will be actually doing the merge later today.