Clarify the audience and goals of the reference.

[ehuss]

I think it would be useful to be explicit about who the reference is for and in what style it should be. There seems to be some uncertainty about being a reference vs a spec or if it should be both. I was confused when I first started, but I've gleaned the following along the way:

• introduction.md says it is "not normative", "not a spec", but a "spec is intended in the future".

• CONTRIBUTING.md: "too teachy for people" and "too shallow for a reference".

• Over chat (some disagreement):

  • @Centril: "supposed to be near-spec-like"
  • @steveklabnik: "the reference is supposed to be spec-like, but not fully spec yet. the end goal is to have it be an actual spec. not there yet"
  • @Havvy: "The reference fills the niche for somebody who's already gone through learning material and needs a refresher or a point of confusion cleared up. Specifications fill the niche of describing the exact semantics of whatever they are specifying. The audiences for these are not the same."

• Rust All Hands 2019: https://paper.dropbox.com/doc/Topic-Spec--AZn5mRiLBp9zayEPAqu4RkjnAg-BB1tcOKwvpWUdzgQO4zgu

  • Was there any outcome from the Rust All Hands discussion?

I think it would be good to write down:

• Who is the audience, and what are the high-level goals?
• What is the intent? Should it be complete enough for someone to write a Rust compiler, parser, or other tooling? A guide for learning details of the language?
• Maybe even dive down into details like style and voice? Is there an established format to follow?
  • This is one place where I see the divide between a formal spec and a natural reference is difficult to bridge. For example, a spec could have every clause numbered, possibly written in formal semantics, perhaps with a test suite for every clause. The difference between natural language and a formal definition can be quite big. Some language specs include both formal and natural language.

I like the general style things have gone so far, in that it is mostly readable for a typical Rust programmer, with illustrative examples. My personal preference would be: continue along the current trajectory of having a non-normative, semi-formal (i.e. not a guide, not a formal spec) reference which strives for complete coverage while remaining semi-neutral to the details of the reference implementation (i.e. doesn't usually delve into usage, bugs, implementation-specific things, etc.). A formal, standards-quality spec is a non-goal at this time, though it is desirable to have such a document in the future (possibly separate or combined?).

Some example specs and references:

• C++: Spec (source)
• C# Reference (same as ECMA-334)
• Go Language Specification
• Java Language Specification
• Javascript: ECMA-262
• Typescript Language Specification
• Scheme
• Standard ML
• Swift Language Reference
• Ada Reference Manual
• Haskell language report
• WASM Spec
• Python Reference
• D Spec
• Racket Reference

Interesting little paper comparing different ways languages are specified: http://www.knosof.co.uk/vulnerabilities/langconform.pdf
How Modula-2 uses both English and VDM-SL to formally define the semantics (and some notes on the spec process in general): https://freepages.modula2.org/downloads/process2.pdf

[petrochenkov]

reference vs a spec

Interesting, I always thought those are the same thing.
For example, ARM Architecture Reference Manual is a specification.

[ehuss]

I always thought those are the same thing.

I'm not aware of any well-defined distinction, and they are sometimes used interchangeably. I've noticed a trend that "spec" is decidedly formal, whereas "reference" can mean anything.

[brauliobz]

I think having two documents would be a lot of unnecessary duplicated work.