Style, formatting, and policy guide

[ehuss]

I think it might be useful to have a guide for style, formatting, and what should and should not be included. If there is, care should be taken to communicate that they are guidelines on how documentation should be written, not necessarily how it must be written, since overly pedantic rules can discourage contribution.

Policy

• When should the reference include why something is done in a particular way? Often the reference avoids the "why", but I think it can sometimes provide interesting context.

  • For example, type_length_limit explains what it does, but not why it is there. I think it could be useful to say something like: type_length_limit is used to prevent the compiler from hanging and to better deal with polymorphic recursion.
  • There are many other examples where the motivation for something is hidden away in some RFC.

• How can reference writers know when something should be intentionally undefined? (Like certain evaluation orders.) Seems like it would be easy to accidentally document some behavior without knowing it shouldn't be specified. Maybe someone in-the-know could call out exactly what should be left undefined, I suspect the list is not very long.

• How to deal with rustc version numbers? Is the rustc version number the same as the "The Rust Language" version number? Should the reference actively avoid mentioning version numbers? In general, they could be useful in some situations, but generally are difficult to mark what is changed/added/removed with enough granularity, and to deal with changes over time. (See Should we document when features are stabilized? #60)

• Should the reference document actual rust behavior (including bugs)? Or should it document the intended behavior? Or both?

  • Related: If there's a known issue, should it be encouraged or discouraged to link to the Github issue?

• Should the reference mention things that are deprecated?

• Should the reference avoid talking about past behavior?

• How should overlap with other documentation be handled? Should the reference duplicate everything and be completely standalone? Or can it link to other books?

  • It could be useful to link to other sources like TRPL. The reference is tends to be terse, and pointing to guide-style documentation could helpful for someone learning how to use something. However, lots of links would be very noisy.

• How should the reference handle rustc-specific things? Where does the line get drawn? What is OK to mention? For example, compiler flags? Should it just be opportunistically helpful? For example, extern crate briefly mentions Cargo's dash-to-underscore rename. Another example: is the filesystem layout part of the language or part of the implementation? What is implementation-specific?

• What is the policy for linking to historical information, such as RFCs, PRs, GitHub issues, blog posts, etc? These sources are mostly static and not updated, and thus may provide outdated or incorrect information. However, as historical context they are useful.

• Should examples be encouraged? Any guidelines for writing examples?

  • naming convention (is foo/bar/baz ok? or should it lean towards realistic examples?)
  • Balancing length vs. clarity.
  • Usage of no_run or ignore.
  • Realistic examples vs trivial examples of code nobody would ever write.

• Guidelines for documenting lints. Generally I think they are always avoided, that's what the rustc book is for.

• Should the reference be agnostic about whether code is "compiled" or "interpreted"? Should it avoid using the term "compile"?

Style

• Spelling (british vs american)
  • Should CI check spelling? TRPL has a spell script with a pre-defined dictionary.txt.
• Should there be recommended English grammar guidelines? AP Style? etc.
• Grammatic person guidelines? Voice?
  • https://ntrs.nasa.gov/archive/nasa/casi.ntrs.nasa.gov/19820007101.pdf
• Various things to avoid?
  • Avoid "in Rust", everything in the reference is about Rust.
  • Avoid foo/bar slashes, use "and" or commas.
• Any guidance on contractions?
• Is E in "2018 Edition" capitalized?
• Explain or define the "style" of the reference. i.e. it is not a "guide". It expresses how things work and behave, not how to use them.
• The prose should probably not repeat the grammar rules. i.e. don't say "an expression followed by an equals sign (=) followed by an expression".

Formatting

• Word wrapping column? 80? 90? 100? No wrapping? No preference? Semantic linefeeds?
  • Should PR's avoid re-wrapping paragraphs to make the diff easier to read, or should they always re-wrap everything?
• Where should Markdown links be placed? Inline, below a section, bottom of file, etc? Should links be alphabetized? Case-sensitive or not?
  • Avoid indenting links for alignment?
• List and document special constructs like "warning", "note", "edition differences" and when to use them. (Formatting for notes is currently inconsistent.)
• Preferred styling for lists - or * or anything?
• Preferred heading format is ATX style?
• Headings should be sentence case? Or Initial Caps?
• Avoid double blank lines (only one blank line between sections)

Links of interest

• https://github.com/rust-lang/book/blob/master/style-guide.md
• https://developers.google.com/style/
• https://docs.microsoft.com/en-us/style-guide/welcome/
• https://github.com/cplusplus/draft/wiki/Specification-Style-Guidelines
• https://github.com/jenniferlynparsons/awesome-writing
• https://www.iso.org/files/live/sites/isoorg/files/archive/pdf/en/how-to-write-standards.pdf

[Centril]

• When should the reference include why something is done in a particular way?

We should be careful not to go too deep into this. In the case of type_length_limit it could be sensible since there's not much else to say.

• How can reference writers know when something should be intentionally undefined? (Like certain evaluation orders.) Seems like it would be easy to accidentally document some behavior without knowing it shouldn't be specified. Maybe someone in-the-know could call out exactly what should be left undefined, I suspect the list is not very long.

We do have a blanket disclaimer noting that parts of the reference is not normative. When there is parts that are undefined / unspecified I think it would be good to call it out explicitly.

• How to deal with rustc version numbers?

I think we should follow latest stable as much as possible and not include version numbers. To do so will become just too messy to maintain. Eventually, rustc should hopefully follow the latest reference version number... or rather, the version number of rustc is that of the spec ;)

Should the reference document actual rust behavior (including bugs)? Or should it document the intended behavior? Or both?

• Related: If there's a known issue, should it be encouraged or discouraged to link to the Github issue?

We should strive to let the reference be as independent as possible. If there are known rustc divergences (e.g. C-future-compatibility bugs), then if they are noted, those should be noted as bugs because rustc is in the wrong. I think that we shouldn't aim to duplicate rustc issue tracking however.

• Should the reference mention things that are deprecated?

If they are part of the language definition, then they must be mentioned. Noting their deprecation is also a good idea imo.

• Should the reference avoid talking about past behavior?

Could you give an example?

• How should overlap with other documentation be handled? Should the reference duplicate everything and be completely standalone? Or can it link to other books?

In my view, the reference should be standalone such that you can remove any mentions to other things at it should still make sense. However, adding "read more" links to other books may make sense in some cases. Also, references referring to various papers and such are not a problem.

• How should the reference handle rustc-specific things? Where does the line get drawn? What is OK to mention? For example, compiler flags? Should it just be opportunistically helpful? For example, extern crate briefly mentions Cargo's dash-to-underscore rename. Another example: is the filesystem layout part of the language or part of the implementation? What is implementation-specific?

In all cases, rustc specific behavior where mentioned should be called out as rustc specific behavior.
Compiler flags should not be documented here and the cargo dash-to-underscore rename is probably out of scope (Cargo is even more peripheral from the reference's POV).

Wrt. filesystem layout, that one is tricky... We have to be careful not to make whole file systems part of the spec. Not sure what the right answer is here...

• What is the policy for linking to historical information, such as RFCs, PRs, GitHub issues, blog posts, etc? These sources are mostly static and not updated, and thus may provide outdated or incorrect information. However, as historical context they are useful.

Examples? I think it's important to note what information is historical when that happens and avoid having it intrude too much on main flow.

Should examples be encouraged? Any guidelines for writing examples?

• naming convention (is foo/bar/baz ok? or should it lean towards realistic examples?)

• Balancing length vs. clarity.

• Usage of no_run or ignore.

• Realistic examples vs trivial examples of code nobody would ever write.

Examples are good but should strive to be complementary as opposed to acting as a source of truth.
I think using foo and bar is fine but if more realistic names make sense for that example without being overly long then that is better.

I think the goal of examples is to demonstrate a particular section of the reference; realistic examples are not necessary... instead, we should use minimalistic examples that carries the point across.

Can you elaborate on no_run vs. ignore?

• Guidelines for documenting lints. Generally I think they are always avoided, that's what the rustc book is for.

Lints are not part of the language definition so yes. Maybe we want to integrate them later into a linting section or denote lint triggers inline; I do think this is something that other Rust compilers would be interested in.

• Should the reference be agnostic about whether code is "compiled" or "interpreted"? Should it avoid using the term "compile"?

Yeah I think the reference should be agnostic unless compilation actually matters (and if it does then 😢).

• Spelling (british vs american)

• Should CI check spelling? TRPL has a spell script with a pre-defined dictionary.txt.

• Should there be recommended English grammar guidelines? AP Style? etc.

• Grammatic person guidelines? Voice?

Prefer standard academic IEEE style guidelines.

CI checking spelling sounds good.
Speaking of CI, I would also globally ban the redundant phrase "in order".
Also look out for weasel words and avoid them (possibly using CI).

• Avoid "in Rust", everything in the reference is about Rust.

Makes sense 👍

• Avoid foo/bar slashes, use "and" or commas.

Sure; and always use an Oxford comma.

Any guidance on contractions?

Never use can't, always use cannot. In general, I think we should generally avoid contractions.

Is E in "2018 Edition" capitalized?

Yes, but I believe we typically use "Rust 2018".

• Explain or define the "style" of the reference. i.e. it is not a "guide". It expresses how things work and behave, not how to use them.

👍

• The prose should probably not repeat the grammar rules. i.e. don't say "an expression followed by an equals sign (=) followed by an expression".

Hmm... it may not be necessary for the grammar but I also don't see the harm. This is what I had in mind for typing rules. It is fairly standard practice in type theory and PLT papers to explain a given set of typing rules in prose afterwards. However, the formal specifications (non-prose) should be what is normative in all cases.

Word wrapping column? 80? 90? 100? No wrapping? No preference? Semantic linefeeds?

Semantic linefeeds or wrapping at 80 characters seems good to me. No wrapping is really hard to review in terms of diffs.

Where should Markdown links be placed? Inline, below a section, bottom of file, etc? Should links be alphabetized? Case-sensitive or not?

Generally, I find that either below a section or bottom of a file is good. Alphabetized (case-insensitive) sounds good.

• List and document special constructs like "warning", "note", "edition differences" and when to use them. (Formatting for notes is currently inconsistent.)

This is where I start to wonder whether markdown is a good idea at all... LaTeX would deal with this nicely and is probably also necessary for typing rules.

Preferred styling for lists - or * or anything?

I personally use + but I would be fine with whatever.

Preferred heading format is ATX style?

Yes, always.

Headings should be sentence case? Or Initial Caps?

Sentence case; these sort of stylistic things should be modified globally if need be (again why LaTeX is nice).

• Avoid double blank lines (only one blank line between sections)

👍

[Havvy]

I have a feeling Github Issues is probably not a good way to process this number of questions.

Policy

* When should the reference include _why_ something is done in a particular way? Often the reference avoids the "why", but I think it can sometimes provide interesting context.
  * For example, `type_length_limit` explains what it does, but not why it is there. I think it could be useful to say something like: `type_length_limit` is used to prevent the compiler from hanging and to better deal with [polymorphic recursion](https://en.wikipedia.org/wiki/Polymorphic_recursion).
  * There are many other examples where the motivation for something is hidden away in some RFC.

If the why is interesting or helps the person understand the existence, sure. "Why do struct literals exist" is a bad question to answer. "Why can't we use struct literals as the trailing subexpression in an if statement" is a good one.

* How can reference writers know when something should be intentionally undefined? (Like certain evaluation orders.) Seems like it would be easy to accidentally document some behavior without knowing it shouldn't be specified. Maybe someone in-the-know could call out exactly what should be left undefined, I suspect the list is not very long.

Anything explicitly left unspecified should be explicitly called out as unspecified somewhere.

* How to deal with rustc version numbers? Is the rustc version number the same as the "The Rust Language" version number? Should the reference actively avoid mentioning version numbers? In general, they could be useful in some situations, but generally are difficult to mark what is changed/added/removed with enough granularity, and to deal with changes over time. (See #60)

The reference ships with a specific version of rustc and is valid for that version. We don't mention that version anywhere. If we have an appendix for new features, we can use the version in those appendices.

* Should the reference document actual rust behavior (including bugs)?  Or should it document the _intended_ behavior? Or both?

  * Related: If there's a known issue, should it be encouraged or discouraged to link to the Github issue?

If the bug is a cause of unsound behavior and it won't get fixed soon, definitely. If it's a limitation on what can be written and won't get fixed soon, probably. If it affects people writing real programs, it should be documented.

* Should the reference mention things that are deprecated?

Like @Centril said, if it's part of the language, it should be documented. We can't "remove" language features, only hide them under edition flags.

* How should overlap with other documentation be handled? Should the reference duplicate everything and be completely standalone? Or can it link to other books?
  
  * It could be useful to link to other sources like TRPL. The reference is tends to be terse, and pointing to guide-style documentation could helpful for someone learning how to use something. However, lots of links would be very noisy.

Preferably, standalone. The reference isn't for people learning how to use something for the first time. If your first look at e.g. enums, is at the reference, you're at the wrong place. As such, we shouldn't cater to people just learning the language for the first time.

* How should the reference handle `rustc`-specific things? Where does the line get drawn? What is OK to mention? For example, compiler flags? Should it just be opportunistically helpful? For example, `extern crate` briefly mentions Cargo's dash-to-underscore rename. Another example: is the filesystem layout part of the language or part of the implementation? What is implementation-specific?

Be explicit when talking about things that are hooked to rustc by putting them in notes. Only include them if it feels like a major omission to not do so. For example, conditional compilation does for arbitrary set compilation keys because not doing so doesn't say how to actually set them.

* What is the policy for linking to historical information, such as RFCs, PRs, GitHub issues, blog posts, etc?  These sources are mostly static and not updated, and thus may provide outdated or incorrect information. However, as historical context they are useful.

Where information is incomplete, linking to more complete documentation can be a temporary workaround. Otherwise, I'd rather not link to all the historical information. Having "The History of Rust" that does this would be a fun read, but having it done half-way inside the reference helps nobody.

* Should examples be encouraged? Any guidelines for writing examples?
  
  * naming convention (is foo/bar/baz ok? or should it lean towards realistic examples?)
  * Balancing length vs. clarity.
  * Usage of `no_run` or `ignore`.
  * Realistic examples vs trivial examples of code nobody would ever write.

Examples are useful for people who just need to see the code to remember something. Realistic examples that don't rely on domain-knowledge of some field (including maths) are nice, but if there's no terse realistic example, an arbitrary example would do better. Length vs. clarity are tradeoffs, but it's hard to give hard advice on it other than with all things being equal, prefer the one that is most clear or shorter.

* Guidelines for documenting lints. Generally I think they are always avoided, that's what the rustc book is for.

Yes.

* Should the reference be agnostic about whether code is "compiled" or "interpreted"? Should it avoid using the term "compile"?

We have a note about this on the crates and source file chapter. If we had a location where we needed to say "compiled or interpreted", I'd rather it just said "compiled". There's no word that means both, right?

Style

* Spelling (british vs american)

American spelling, as much as I'd rather have British.

  * Should CI check spelling? TRPL has a spell script with a pre-defined dictionary.txt.

If somebody set this up, I wouldn't be opposed.

* Should there be recommended English grammar guidelines? AP Style? etc.

I don't know if this is necessary.

* Grammatic person guidelines?  Voice?
  
  * https://ntrs.nasa.gov/archive/nasa/casi.ntrs.nasa.gov/19820007101.pdf

Whichever is more clear should be used.

* Various things to avoid?
  
  * Avoid "in Rust", everything in the reference is about Rust.
  * Avoid foo/bar slashes, use "and" or commas.

I'd add parentheticals to that list. More sentences are usually fine, and usually more quotable.

* Any guidance on contractions?

Don't.

* Is `E` in "2018 Edition" capitalized?

This is a question for Rust Marketing™ to answer.

* Explain or define the "style" of the reference. i.e. it is not a "guide". It expresses how things work and behave, not how to use them.

Is this not already done on the introduction page?

* The prose should probably not repeat the grammar rules. i.e. don't say "an expression followed by an equals sign (`=`) followed by an expression".

No comment here.

Formatting

* Word wrapping column? 80? 90? 100? No wrapping? No preference? [Semantic linefeeds](https://rhodesmill.org/brandon/2012/one-sentence-per-line/)?

Wrap at 80, except link refs.

  * Should PR's avoid re-wrapping paragraphs to make the diff easier to read, or should they always re-wrap everything?

The current behavior is to re-wrap, even if the PRs are harder to understand.

* Where should Markdown links be placed? Inline, below a section, bottom of file, etc? Should links be alphabetized? Case-sensitive or not?

Right now the sorta-standard is alphabetized, case-sensitive, with links at the bottom. We could do away with the case-sensitive question and make all link refs all-lowercase. All link refs should be at the bottom of the file unless there's a lot of linking in one section that is out-of-the-norm in the kind of links from the rest of the document.

  * Avoid indenting links for alignment?

Yes.

* List and document special constructs like "warning", "note", "edition differences" and when to use them. (Formatting for notes is currently inconsistent.)

The formatting is specified on the introduction page. If something is inconsistent with that, it should be fixed. I'd like to do wiki-template style {{warning|whatever}} (but not necessarily that exact syntax) instead of having to code it the same way everywhere.

* Preferred styling for lists `-` or `*` or anything?

I prefer using asterisks, but I don't think it ultimately matters.

* Preferred heading format is ATX style?

Yes.

* Headings should be sentence case? Or Initial Caps?

I just want us to pick one. @Centril gives a good argument for sentence case.

* Avoid double blank lines (only one blank line between sections)

Yes. Don't block a PR on this though.

[ehuss]

Should the reference avoid talking about past behavior?
Could you give an example?

See

• The note at the end of this section.
• The note at the end of this section.
• Mention of 1.26 here.

What is the policy for linking to historical information
Examples?

• Every mention of an RFC throughout the text (I count about 10).
• Every link to https://github.com/rust-lang/rust/issues (I count about 4 or so).

Can you elaborate on no_run vs. ignore?

Code examples marked with ignore are not compiled. Examples with no_run are compiled, but not executed during tests. I think ignore should be avoided if possible (unfortunately there are many cases where it is required). Too often ignored examples end up containing invalid code.

Should the reference mention things that are deprecated?
if it's part of the language, it should be documented.

I think I meant this in a different way. Deprecations are usually implemented as lints, which means the reference is now including lints. I definitely think deprecations should be included, I meant that this rule presents an exception to the rules of "don't document lints" and "don't include future functionality" (usually these are worded as "will become a hard error in the future" which I think is fine, but a violation of talking about future functionality).

[Centril]

The note at the end of this section.

Drop it; we don't actually make this recommendation and I think such "how should I write my code"-tips is not interesting for the reference. This is more appropriate for API-guidelines.

The note at the end of this section.

This one seems reasonable to keep; as it explains why something that is seemingly redundant otherwise is supported.

Mention of 1.26 here.

I wouldn't have added the caveat about the version... fortunately, the bare trait object style will just become deprecated and so we can note that; in Rust 2021 it might (I hope) become a hard error.

• Every mention of an RFC throughout the text (I count about 10).

• Every link to https://github.com/rust-lang/rust/issues (I count about 4 or so).

If we take an example such as https://doc.rust-lang.org/nightly/reference/items/traits.html#object-safety, I would make the reference to the RFC either into a proper IEEE style citation or a footnote. These are imo the proper way to have an aside note without impeding main reading flow.

Code examples marked with ignore are not compiled. Examples with no_run are compiled, but not executed during tests. I think ignore should be avoided if possible (unfortunately there are many cases where it is required). Too often ignored examples end up containing invalid code.

Use the "strictest" mode possible whatever that means. E.g. if you want to ensure compilation failure, then check that it actually fails to compile with compile_fail; I think we should try to avoid no_run as well but your point re. ignore is good.

I think I meant this in a different way. Deprecations are usually implemented as lints, which means the reference is now including lints. I definitely think deprecations should be included, I meant that this rule presents an exception to the rules of "don't document lints"

I agree with this. As we beef up the reference I think normal lints can also be included as a non-normative but recommended part of a Rust compiler / interpreter.

usually these are worded as "will become a hard error in the future" which I think is fine, but a violation of talking about future functionality).

Note that C-future-compatibility lints are an exception to the exception; they are rustc bugs which are deviations from "the spec". When they occur, the reference should document the intended behavior and not the rustc bug and then rustc should conform to the reference. (caveats may be included...)