rollup merge of #22331: steveklabnik/guidelines

Fixes #19315

r? @aturon

Author: alexcrichton

mk/docs.mk

@@ -73,7 +73,7 @@ RUSTBOOK = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(RUSTBOOK_EXE)
 
 D := $(S)src/doc
 
-DOC_TARGETS := trpl
+DOC_TARGETS := trpl style
 COMPILER_DOC_TARGETS :=
 DOC_L10N_TARGETS :=
 
@@ -275,3 +275,9 @@ trpl: doc/book/index.html
 doc/book/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/trpl/*.md) | doc/
 	$(Q)rm -rf doc/book
 	$(Q)$(RUSTBOOK) build $(S)src/doc/trpl doc/book
+
+style: doc/style/index.html
+
+doc/style/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/style/*.md) | doc/
+	$(Q)rm -rf doc/style
+	$(Q)$(RUSTBOOK) build $(S)src/doc/style doc/style

src/doc/style/README.md

@@ -0,0 +1,64 @@
+% Style Guidelines
+
+This document collects the emerging principles, conventions, abstractions, and
+best practices for writing Rust code.
+
+Since Rust is evolving at a rapid pace, these guidelines are
+preliminary. The hope is that writing them down explicitly will help
+drive discussion, consensus and adoption.
+
+Whenever feasible, guidelines provide specific examples from Rust's standard
+libraries.
+
+### Guideline statuses
+
+Every guideline has a status:
+
+* **[FIXME]**: Marks places where there is more work to be done. In
+  some cases, that just means going through the RFC process.
+
+* **[FIXME #NNNNN]**: Like **[FIXME]**, but links to the issue tracker.
+
+* **[RFC #NNNN]**: Marks accepted guidelines, linking to the rust-lang
+  RFC establishing them.
+
+### Guideline stabilization
+
+One purpose of these guidelines is to reach decisions on a number of
+cross-cutting API and stylistic choices. Discussion and development of
+the guidelines will happen primarily on http://discuss.rust-lang.org/,
+using the Guidelines category. Discussion can also occur on the
+[guidelines issue tracker](https://github.com/rust-lang/rust-guidelines).
+
+Guidelines that are under development or discussion will be marked with the
+status **[FIXME]**, with a link to the issue tracker when appropriate.
+
+Once a concrete guideline is ready to be proposed, it should be filed
+as an [FIXME: needs RFC](https://github.com/rust-lang/rfcs). If the RFC is
+accepted, the official guidelines will be updated to match, and will
+include the tag **[RFC #NNNN]** linking to the RFC document.
+
+### What's in this document
+
+This document is broken into four parts:
+
+* **[Style](style/README.md)** provides a set of rules governing naming conventions,
+  whitespace, and other stylistic issues.
+
+* **[Guidelines by Rust feature](features/README.md)** places the focus on each of
+  Rust's features, starting from expressions and working the way out toward
+  crates, dispensing guidelines relevant to each.
+
+* **Topical guidelines and patterns**. The rest of the document proceeds by
+  cross-cutting topic, starting with
+  [Ownership and resources](ownership/README.md).
+
+* **[APIs for a changing Rust](changing/README.md)**
+  discusses the forward-compatibility hazards, especially those that interact
+  with the pre-1.0 library stabilization process.
+
+> **[FIXME]** Add cross-references throughout this document to the tutorial,
+> reference manual, and other guides.
+
+> **[FIXME]** What are some _non_-goals, _non_-principles, or _anti_-patterns that
+> we should document?

src/doc/style/SUMMARY.md

@@ -0,0 +1,54 @@
+# Summary
+
+* [Style](style/README.md)
+    * [Whitespace](style/whitespace.md)
+    * [Comments](style/comments.md)
+    * [Braces, semicolons, commas](style/braces.md)
+    * [Naming](style/naming/README.md)
+        * [Ownership variants](style/naming/ownership.md)
+        * [Containers/wrappers](style/naming/containers.md)
+        * [Conversions](style/naming/conversions.md)
+        * [Iterators](style/naming/iterators.md)
+    * [Imports](style/imports.md)
+    * [Organization](style/organization.md)
+* [Guidelines by Rust feature](features/README.md)
+    * [Let binding](features/let.md)
+    * [Pattern matching](features/match.md)
+    * [Loops](features/loops.md)
+    * [Functions and methods](features/functions-and-methods/README.md)
+        * [Input](features/functions-and-methods/input.md)
+        * [Output](features/functions-and-methods/output.md)
+        * [For convenience](features/functions-and-methods/convenience.md)
+    * [Types](features/types/README.md)
+        * [Conversions](features/types/conversions.md)
+        * [The newtype pattern](features/types/newtype.md)
+    * [Traits](features/traits/README.md)
+        * [For generics](features/traits/generics.md)
+        * [For objects](features/traits/objects.md)
+        * [For overloading](features/traits/overloading.md)
+        * [For extensions](features/traits/extensions.md)
+        * [For reuse](features/traits/reuse.md)
+        * [Common traits](features/traits/common.md)
+    * [Modules](features/modules.md)
+    * [Crates](features/crates.md)
+* [Ownership and resources](ownership/README.md)
+    * [Constructors](ownership/constructors.md)
+    * [Builders](ownership/builders.md)
+    * [Destructors](ownership/destructors.md)
+    * [RAII](ownership/raii.md)
+    * [Cells and smart pointers](ownership/cell-smart.md)
+* [Errors](errors/README.md)
+    * [Signaling](errors/signaling.md)
+    * [Handling](errors/handling.md)
+    * [Propagation](errors/propagation.md)
+    * [Ergonomics](errors/ergonomics.md)
+* [Safety and guarantees](safety/README.md)
+    * [Using unsafe](safety/unsafe.md)
+    * [Library guarantees](safety/lib-guarantees.md)
+* [Testing](testing/README.md)
+    * [Unit testing](testing/unit.md)
+* [FFI, platform-specific code](platform.md)
+* [APIs for a changing Rust](changing/README.md)
+    * [Pre-1.0 changes](changing/pre-1-0.md)
+    * [Post-1.0 changes](changing/post-1-0.md)
+    * [Timing unclear](changing/unclear.md)

src/doc/style/changing/README.md

@@ -0,0 +1,5 @@
+% API design for a changing Rust
+
+A number of planned Rust features will drastically affect the API design
+story. This section collects some of the biggest features with concrete examples
+of how the API will change.

src/doc/style/changing/post-1-0.md

@@ -0,0 +1,12 @@
+% Post-1.0 changes
+
+### Higher-kinded types
+
+* A trait encompassing both `Iterable<T>` for some fixed `T` and
+  `FromIterator<U>` for _all_ `U` (where HKT comes in).  The train
+  could provide e.g. a default `map` method producing the same kind of
+  the container, but with a new type parameter.
+
+* **Monadic-generic programming**? Can we add this without deprecating
+  huge swaths of the API (including `Option::map`, `option::collect`,
+  `result::collect`, `try!` etc.

src/doc/style/changing/pre-1-0.md

@@ -0,0 +1,17 @@
+% Pre-1.0 changes
+
+### `std` facade
+
+We should revisit some APIs in `libstd` now that the facade effort is complete.
+
+For example, the treatment of environment variables in the new
+`Command` API is waiting on access to hashtables before being
+approved.
+
+### Trait reform
+
+Potential for standard conversion traits (`to`, `into`, `as`).
+
+Probably many other opportunities here.
+
+### Unboxed closures

src/doc/style/changing/unclear.md

@@ -0,0 +1,28 @@
+% Changes with unclear timing
+
+### Associated items
+
+* Many traits that currently take type parameters should instead use associated
+  types; this will _drastically_ simplify signatures in some cases.
+
+* Associated constants would be useful in a few places, e.g. traits for
+  numerics, traits for paths.
+
+### Anonymous, unboxed return types (aka `impl Trait` types)
+
+* See https://github.com/rust-lang/rfcs/pull/105
+
+* Could affect API design in several places, e.g. the `Iterator` trait.
+
+### Default type parameters
+
+We are already using this in a few places (e.g. `HashMap`), but it's
+feature-gated.
+
+### Compile-time function evaluation (CTFE)
+
+https://github.com/mozilla/rust/issues/11621
+
+### Improved constant folding
+
+https://github.com/rust-lang/rust/issues/7834

src/doc/style/errors/README.md

@@ -0,0 +1,3 @@
+% Errors
+
+> **[FIXME]** Add some general text here.

src/doc/style/errors/ergonomics.md

@@ -0,0 +1,66 @@
+% Ergonomic error handling
+
+Error propagation with raw `Result`s can require tedious matching and
+repackaging. This tedium is largely alleviated by the `try!` macro,
+and can be completely removed (in some cases) by the "`Result`-`impl`"
+pattern.
+
+### The `try!` macro
+
+Prefer
+
+```rust
+use std::io::{File, Open, Write, IoError};
+
+struct Info {
+    name: String,
+    age: int,
+    rating: int
+}
+
+fn write_info(info: &Info) -> Result<(), IoError> {
+    let mut file = File::open_mode(&Path::new("my_best_friends.txt"),
+                                   Open, Write);
+    // Early return on error
+    try!(file.write_line(format!("name: {}", info.name).as_slice()));
+    try!(file.write_line(format!("age: {}", info.age).as_slice()));
+    try!(file.write_line(format!("rating: {}", info.rating).as_slice()));
+    return Ok(());
+}
+```
+
+over
+
+```rust
+use std::io::{File, Open, Write, IoError};
+
+struct Info {
+    name: String,
+    age: int,
+    rating: int
+}
+
+fn write_info(info: &Info) -> Result<(), IoError> {
+    let mut file = File::open_mode(&Path::new("my_best_friends.txt"),
+                                   Open, Write);
+    // Early return on error
+    match file.write_line(format!("name: {}", info.name).as_slice()) {
+        Ok(_) => (),
+        Err(e) => return Err(e)
+    }
+    match file.write_line(format!("age: {}", info.age).as_slice()) {
+        Ok(_) => (),
+        Err(e) => return Err(e)
+    }
+    return file.write_line(format!("rating: {}", info.rating).as_slice());
+}
+```
+
+See
+[the `result` module documentation](http://static.rust-lang.org/doc/master/std/result/index.html#the-try!-macro)
+for more details.
+
+### The `Result`-`impl` pattern [FIXME]
+
+> **[FIXME]** Document the way that the `io` module uses trait impls
+> on `IoResult` to painlessly propagate errors.

src/doc/style/errors/handling.md

@@ -0,0 +1,7 @@
+% Handling errors
+
+### Use task isolation to cope with failure. [FIXME]
+
+> **[FIXME]** Explain how to isolate tasks and detect task failure for recovery.
+
+### Consuming `Result` [FIXME]