update documentation of tuple/unit structs #33250

durka · 2016-04-28T03:30:29Z

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 @GuillaumeGomez

@ubsan

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

durka · 2016-04-28T03:33:55Z

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.


This sentence could be confusing even though I get what it is trying to say. Color(0, 0, 0) and Color(0, 0, 0) are also not "equal" in some sense because we didn't derive PartialEq.

Maybe it should just say "are not the same type, even though they contain the same values".

Excellent idea! Your second suggestion is just perfect. Could you replace the sentence please?

strega-nil · 2016-04-28T05:08:30Z

I'm of the opinion it should show both ways, or only struct Doop;. I think that's still the preferred way to create a unit struct.

durka · 2016-04-28T05:12:32Z

That's the opposite of the advice you gave me on IRC :)

The RFC doesn't say anything about this -- it says if you have struct Doop; then you should initialize/match it without braces, but it doesn't suggest one form or another. I thought the intention was that once braced_empty_structs was stable, we should prefer it for consistency.

I now think the book should show both ways, but maybe handwave over the type/value namespace thing (leave that to the reference).

GuillaumeGomez · 2016-04-28T06:58:35Z

@durka: If the empty braces are stable then yes. Adding features in documentation would make the whole a lot more complicated. Let's wait for @steveklabnik's confirmation.

GuillaumeGomez · 2016-04-28T07:00:04Z

src/doc/book/structs.md

+`let`, just like regular tuples:
+
+```rust
+# struct Color(i32, i32, i32);


Why the '#' at the beginning of the line?

To hide the line from the documentation, while it's needed to make the example self-contained it's repetitive from the example above.

steveklabnik · 2016-04-28T14:27:58Z

I am not sure what the preferred way should be, to be honest.

steveklabnik · 2016-04-28T14:30:49Z

I am generally pro this patch, but yeah, the conventions question is interesting. @aturon ?

apasel422 · 2016-04-28T14:45:19Z

src/doc/book/structs.md

+let integer_length = length.0;
+```
+
+It's always possible to use a `struct` than a tuple struct, and can be clearer.


s/than/instead of/

GuillaumeGomez · 2016-04-28T15:54:45Z

r=me @steveklabnik

durka · 2016-05-06T17:53:39Z

Any interest in committing to a convention here?

strega-nil · 2016-05-06T20:53:48Z

Hmm, I'm of the opinion that struct Struct; should be preferred, although struct Struct {} should also be introduced.

durka · 2016-05-06T20:57:38Z

@ubsan any reasoning behind that, or just aesthetics?

durka · 2016-05-06T20:58:30Z

To take a counter-position (I truly don't feel strongly): struct Struct {} doesn't pollute the value namespace, and it is more consistent with other {}-structs (though not with tuple structs).

steveklabnik · 2016-07-05T17:23:45Z

I do not want to block this PR on a conventions question we don't have a good way to answer. @durka can you update it with showing both forms, please? And then r=me after.

durka · 2016-07-05T17:46:21Z

Done.

steveklabnik · 2016-07-05T17:50:32Z

@bors: r+ rollup

Thanks! :)

bors · 2016-07-05T17:50:33Z

📌 Commit 74e9629 has been approved by steveklabnik

@ubsan

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 @GuillaumeGomez

@ubsan

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 @GuillaumeGomez

@ubsan

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 @GuillaumeGomez

Rollup of 15 pull requests - Successful merges: #33250, #33265, #34277, #34327, #34521, #34558, #34615, #34619, #34621, #34625, #34626, #34636, #34664, #34667, #34685 - Failed merges: #33951

rust-highfive assigned steveklabnik Apr 28, 2016

durka reviewed Apr 28, 2016
View reviewed changes

fix Point destructuring example

a14df5c

GuillaumeGomez reviewed Apr 28, 2016
View reviewed changes

"equal" -> "same type"

beec630

apasel422 reviewed Apr 28, 2016
View reviewed changes

durka added 2 commits April 28, 2016 10:47

s/than/instead of/

e1e4fbd

add link to match section

56f24d7

show both forms of empty struct declaration

74e9629

steveklabnik mentioned this pull request Jul 5, 2016

Rollup of 13 pull requests #34670

Closed

steveklabnik mentioned this pull request Jul 5, 2016

Rollup of 12 pull requests #34671

Closed

steveklabnik mentioned this pull request Jul 6, 2016

Rollup of 15 pull requests #34695

Merged

bors merged commit 74e9629 into rust-lang:master Jul 7, 2016

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

update documentation of tuple/unit structs #33250

update documentation of tuple/unit structs #33250

durka commented Apr 28, 2016 •

edited

Loading

durka Apr 28, 2016

durka Apr 28, 2016

GuillaumeGomez Apr 28, 2016

strega-nil commented Apr 28, 2016

durka commented Apr 28, 2016 •

edited

Loading

GuillaumeGomez commented Apr 28, 2016

GuillaumeGomez Apr 28, 2016

durka Apr 28, 2016

steveklabnik commented Apr 28, 2016

steveklabnik commented Apr 28, 2016

apasel422 Apr 28, 2016

durka Apr 28, 2016

GuillaumeGomez commented Apr 28, 2016

durka commented May 6, 2016

strega-nil commented May 6, 2016

durka commented May 6, 2016

durka commented May 6, 2016 •

edited

Loading

steveklabnik commented Jul 5, 2016

durka commented Jul 5, 2016

steveklabnik commented Jul 5, 2016

bors commented Jul 5, 2016

update documentation of tuple/unit structs #33250

update documentation of tuple/unit structs #33250

Conversation

durka commented Apr 28, 2016 • edited Loading

durka Apr 28, 2016

Choose a reason for hiding this comment

durka Apr 28, 2016

Choose a reason for hiding this comment

GuillaumeGomez Apr 28, 2016

Choose a reason for hiding this comment

strega-nil commented Apr 28, 2016

durka commented Apr 28, 2016 • edited Loading

GuillaumeGomez commented Apr 28, 2016

GuillaumeGomez Apr 28, 2016

Choose a reason for hiding this comment

durka Apr 28, 2016

Choose a reason for hiding this comment

steveklabnik commented Apr 28, 2016

steveklabnik commented Apr 28, 2016

apasel422 Apr 28, 2016

Choose a reason for hiding this comment

durka Apr 28, 2016

Choose a reason for hiding this comment

GuillaumeGomez commented Apr 28, 2016

durka commented May 6, 2016

strega-nil commented May 6, 2016

durka commented May 6, 2016

durka commented May 6, 2016 • edited Loading

steveklabnik commented Jul 5, 2016

durka commented Jul 5, 2016

steveklabnik commented Jul 5, 2016

bors commented Jul 5, 2016

durka commented Apr 28, 2016 •

edited

Loading

durka commented Apr 28, 2016 •

edited

Loading

durka commented May 6, 2016 •

edited

Loading