API comment conventions

[steveklabnik]

Rendered

I'm mostly trying to codify what we already have consensus on, rather than address every possible question. I can forsee this kind of RFC getting very bogged down in a number of different details, and we can always add more things in a future RFC.

[sfackler]

Might be worth adding conventions for code examples as well. Should "boilerplate" code be hidden with # foo or should all of the setup be displayed (e.g. here)? Should we prefer assert_eq!(foo, bar) or println!("{}", foo); // prints "bar", which I've seen in some places?

I've also been using ## instead of # for section headers since rustdoc turns # into <h1> blocks which looks a bit funky. That's probably something that should be fixed in rustdoc though.

[steveklabnik]

I've also been using ## instead of # for section headers since rustdoc turns # into <h1> blocks which looks a bit funky. That's probably something that should be fixed in rustdoc though.

This is an argument I had before and lost. I feel strongly that it should be ##, but others feel it should be #, and Rustdoc should spit out an <h2>.

[steveklabnik]

Should we prefer assert_eq!(foo, bar) or println!("{}", foo); // prints "bar", which I've seen in some places?

This is a good question, but I don't think there's a consensus yet.

[sfackler]

If we go the println! route, we'll probably want to add some compiletest style logic to make sure it's printing what we expect.

[mdinger]

s/indivudal/individual/

[huonw]

This is an argument I had before and lost. I feel strongly that it should be ##, but others feel it should be #, and Rustdoc should spit out an

.

FWIW, I don't remember you explicitly losing: it was just the overwhelming convention at the time to use # and so easier to ensure everything uses that, with the explicit option to switch to ## if that was what we decided (at least, that's the impression I remember from the discussion at the time: I personally have no particular desire for # over ##, just a desire for consistency).

[huonw]

I feel that it is somewhat important to do a proper citation for academic papers, since the link may die (or be paywalled or whatever) so having the author/title information allows people to track it down.

[steveklabnik]

But aren't there a few different 'proper citations'? I'll admit that I'm a bit unfamilliar.

[cgaebel]

Why is this even a rule?

[huonw]

@steveklabnik sure, there's various ways of doing a 'proper' citation (I don't even know what they are/how to write them by hand; I just use whatever BibTeX spits out), but that doesn't mean we should just give up on a long form entirely. :)

I guess we could chose one of the formal specifications, but it seems extremely low-priority since we don't cite things particularly often.

[nrc]

As long as you have the title, authors, and year, any format is OK, but having those things is standard academically and makes things easy to find.

[sinistersnare]

Is there ever a time where we have said "use block comments?"

The only person I have seen in support of them was @nikomatsakis, but if they are not recommended, then should we remove them from the language? It would simplify the comment story, and if there is significant want for it, it can be re-added in a backwards compatible manner.

I could write up the RFC and implement it (maybe id need some help though...)

[sfackler]

I'm not sure about the utility of block doc comments, but basic /* */ comments are great for commenting out big chunks of code.

[sinistersnare]

Any editor in popular use has some sort of ctrl+/ to comment out a block of code, and they usually even are toggleable, making it much easier than block comments in my opinion.

[sfackler]

Block comments are also the only option if you want to cut out the middle of a line.

[sinistersnare]

Is that used enough to matter? Do you think it may be a good idea to put something up on discourse and maybe see what people think? I have never seen block comments be recommended, so it may be good to remove them. Also i hate the fact that /**/ is not valid, and at the very least i would like to see that fixed :)

[mdinger]

Any editor in popular use has some sort of ctrl+/ to comment out a block of code, and they usually even are toggleable, making it much easier than block comments in my opinion.

I didn't know that. Notepad++ does but it uses block comments to do it...it might be using C++ rules though...not sure. Does Gedit & Vim? Vim probably can because it can do anything. I'll have to check next time I can. playpen doesn't seem to.

Useful for debugging. Just not recommended to push into commits. Also doesn't rely on that block comment feature being there.

[steveklabnik]

@huonw

FWIW, I don't remember you explicitly losing

Fair enough. I had submitted a patch to turn them all into ##, so I remember it differently. But it doesn't really matter, it's not something I'm upset about 😄

[steveklabnik]

I would support removing block comments, but let's please keep that out of this RFC. Removing them would be another, it's just noise here.

[nodakai]

This should perhaps be merged into the Rust Guideline.

[cgaebel]

This is really lame. If there's a single example (as is true in the vast majority of cases), the singular form should be used because that's how English works.

Tooling can use the regex Examples? instead of Examples. If the tool authors can't figure this out, we need better tool authors.

[huonw]

@cgaebel you're getting quite aggressive, could I ask you to tone it down a little?

[nrc]

+1 for singular "example"

[steveklabnik]

An additional reason to use 'Examples' is becaue there should be more than one in most cases, and even if there is only one and they change later, the only part of the diff that changes is the addition of the example itself.

[nikomatsakis]

So, I wonder @steveklabnik why you recommend writing comments inline? It seems like it's strictly less readable. However, I do wonder if we're talking about the same thing. To be clear, I prefer:

Go [read the fine manual][rtfm] my friend

[rtfm]: http://foo.com

or

Go [read the fine manual] my friend

[read the fine manual]: http://foo.com

to

Go [read the fine manual](http://foo.com) my friend

[steveklabnik]

@nikomatsakis I'm fine with either of those. I've historically just done number one, that part is kind of a straw-man.

[sinistersnare]

I prefer inline links too, and I dont believe them to be strictly more readable, with citation style, you need to go to the bottom, see where it links to then scroll back up. Thats just an example, like all stylistic choices, pick one.

I consider inline easier to write, so ill +1 for that subjective reason.

[huonw]

@sinistersnare the rendered docs display the same, and one often puts citation-style just after the paragraph/section where they are used (at least, I do).

[nagisa]

You don’t need to put “citation” links at the bottom. I tend to leave them just after paragraph where I used it. I dislike inline links as they don’t always fit into a line and you get something ugly like:

This is research on the [best languages]
(http://example.com/unbearably/long/path/to/the/paper.pdf?with=true&alot=indeed&ofparams&authorised=✓)
I’ve conducted. Be sure to read that.

[nrc]

This seems a little english-centric for generic guidelines - how about "All doc comments, ..., should be properly punctuated, full sentences."

[nagisa]

All documentation is standardized on American English, with regards to spelling, grammar, and punctuation conventions.

Source

[nrc]

Yep, I think that is wrong too.

[bluss]

Function / method documentation — do we have a good style suggestion for how to write parameter and return value documentation? Good documentation should contain all of this I guess: brief summary, documented parameters and return type, panic cases (if any), and an example.

About emphasis in function / method documentation: In my own code I have started to mark up parameter names (foo) and values (None, true) and class names (Graph<N, E>) in boldface. Parameters and classes are bold in rustdoc's markup, and the gray box around backtick text does not look good at all (Graph<N, E>) — for example "None" is bold and colorful in rustdoc's autogenerated documentation, I want to emulate that in my documentation text. None is the closest I can be with simple markup.

[nagisa]

In my own code I have started to mark up parameter names (foo) and values (None, true) and class names (Graph<N, E>) in boldface

Actually, rustdoc should be made to link to these automatically or at least semi-automatically with annotations (such as the aforementioned graves).

[bluss]

Should we prefer assert!(a == b) or assert_eq!(a, b) in examples? The question spawned here

I think we should use assert!() and the reasoning is

this is neither in testing code nor in actual code but from an example in the documentation, a case of its own.

I prefer to use assert!(a == b) in examples, when "demoing" equality while making sure the example is testable. (Remember it is an example in the documentation as first priority, and testable code to make sure the example works is second priority.)

I prefer assert!(a == b) thinking that the reader of the documentation will find it more obvious.

[steveklabnik]

@bluss

do we have a good style suggestion for how to write parameter and return value documentation?

We don't currently do this much in the standard library, so I'm leaving it off for now. If rustdoc grows this kind of thing, we should add it then, imho.

Should we prefer assert!(a == b) or assert_eq!(a, b) in examples?

My understanding is that assert! == doesn't work anymore, though I can't quite remember why.

[steveklabnik]

@nikomatsakis updated regarding 'citation style', I was confused as to what exactly you were talking about originally.

[steveklabnik]

Whew! It's time to get this RFC shipped. Thank you all for your comments a while back, and sorry I couldn't get to them sooner.

I think this is in a pretty decent place now. It doesn't cover every single possibility, but I think it's a base we can work from. I would prefer to ship a smaller RFC that we can all agree on and then add things than argue endlessly about every last convention. :)

[seanmonstar]

My understanding is that assert! == doesn't work anymore, though I can't quite remember why.

Wait what? That can't be right. == returns a bool, and assert acts on a bool...

[steveklabnik]

Searching on the issue tracker for that is likely to be hard, I think it was @alexcrichton ?

[bluss]

I think you refer to the fact that we can't special-case the assert!(x == y) macro because we can't match on arbitrary tokens like == anymore.

Anyway, maybe this is an ex-issue? assert_eq! is cryptic but if we use it everywhere, users of documentation are forced to learn it. Ideally for me, there should be a clearer, prettier way to write documentation examples that simultaneously demonstrate a fact while making it testable automatically.

[steveklabnik]

On IRC, it was mentioned that it was about error messages, basically assert_eq! gives better ones, that's why it still exists.

[bluss]

Yeah. I hope in the future we'll just have some other more awesome (and easier to read) way to write testable examples without using either of the two assert macros.

[nikomatsakis]

We (the core team) have decided to merge this RFC so that we at least have some official style guidelines to use. To a large extent, this RFC simply formalizes existing practice. We can always revise if/as needed. This is the first "style" RFC, so it's expected that we'll want to perhaps integrate these suggestions into a broader style guide when we decide to tackle that topic.