update documentation of tuple/unit structs

I made the "tuple structs are useless" editorializing a bit weaker and moved it to the end. Feel free to overrule me on that.

I also added an example of how to unpack a tuple struct with dot notation, because it came up on IRC.

`braced_empty_structs` is stable now, so I updated the example for unit-like structs to use that syntax. Should we show both ways?

cc @ubsan
r? @steveklabnik or @GuillameGomez

diff --git a/src/doc/book/structs.md b/src/doc/book/structs.md
index b2fddf336273fe0d1f3d663e7bd09886579e41fb..404eac25308c067dd7d0881a527c29ebf8015aa0 100644 (file)
--- a/src/doc/book/structs.md
+++ b/src/doc/book/structs.md
@@ -163,11 +163,48 @@ struct Point(i32, i32, i32);
 let black = Color(0, 0, 0);
 let origin = Point(0, 0, 0);
 ```
+
 Here, `black` and `origin` are not equal, even though they contain the same
 values.
 
-It is almost always better to use a `struct` than a tuple struct. We
-would write `Color` and `Point` like this instead:
+The members of a tuple struct may be accessed by dot notation or destructuring
+`let`, just like regular tuples:
+
+```rust
+# struct Color(i32, i32, i32);
+# struct Point(i32, i32, i32);
+# let black = Color(0, 0, 0);
+# let origin = Point(0, 0, 0);
+let black_r = black.0;
+let (_, origin_y, origin_z) = origin;
+```
+
+One case when a tuple struct is very useful is when it has only one element.
+We call this the ‘newtype’ pattern, because it allows you to create a new type
+that is distinct from its contained value and also expresses its own semantic
+meaning:
+
+```rust
+struct Inches(i32);
+
+let length = Inches(10);
+
+let Inches(integer_length) = length;
+println!("length is {} inches", integer_length);
+```
+
+As above, you can extract the inner integer type through a destructuring `let`.
+In this case, the `let Inches(integer_length)` assigns `10` to `integer_length`.
+We could have used dot notation to do the same thing:
+
+```rust
+# struct Inches(i32);
+# let length = Inches(10);
+let integer_length = length.0;
+```
+
+It's always possible to use a `struct` than a tuple struct, and can be clearer.
+We would write `Color` and `Point` like this instead:
 
 ```rust
 struct Color {
@@ -187,32 +224,14 @@ Good names are important, and while values in a tuple struct can be
 referenced with dot notation as well, a `struct` gives us actual names,
 rather than positions.
 
-There _is_ one case when a tuple struct is very useful, though, and that is when
-it has only one element. We call this the ‘newtype’ pattern, because
-it allows you to create a new type that is distinct from its contained value
-and also expresses its own semantic meaning:
-
-```rust
-struct Inches(i32);
-
-let length = Inches(10);
-
-let Inches(integer_length) = length;
-println!("length is {} inches", integer_length);
-```
-
-As you can see here, you can extract the inner integer type through a
-destructuring `let`, as with regular tuples. In this case, the
-`let Inches(integer_length)` assigns `10` to `integer_length`.
-
 # Unit-like structs
 
 You can define a `struct` with no members at all:
 
 ```rust
-struct Electron;
+struct Electron {}
 
-let x = Electron;
+let x = Electron {};
 ```
 
 Such a `struct` is called ‘unit-like’ because it resembles the empty