Split Types Chapter #454

ehuss · 2018-10-17T01:58:22Z

This splits the types chapter into multiple subchapters.

I tried to avoid content changes, but I ended up with a few changes:

Added overview links in types.md, and a separate discussion of type expressions.
Split array and slice into separate chapters. Although there is some overlap between them, I feel like it was awkward explaining one and then the other. I also felt it conflated the two too much since slices can be used for more than arrays.
Combined Self section with the one on the paths page.
Added a basic redirector for external links.

Some pages may seem a little bare now, but I think each type page has potential to be expanded and improved in the future.

Closes #445.

ehuss · 2018-10-17T01:59:14Z

Some things I'd like feedback on:

Should the user-defined types (struct/enum/union) be combined into a single page? I feel like its awkward that there are two places to describe them (type and item pages), and that there is already some overlap with the item pages. I think it might be better to avoid the duplication, and leave the type page relatively basic.
- The discussion of "recursive types" could maybe be moved to this combined user-type page.
I'm not confident the list of types that can be specified with Type Paths is complete.

Havvy · 2018-10-23T05:25:48Z

src/SUMMARY.md

+        - [Boolean type](types/boolean-type.md)
+        - [Numeric types](types/numeric-type.md)
+        - [Textual types](types/textual-type.md)
+        - [Never type](types/never-type.md)


The Never type should be removed. It's not stable and was added during the brief couple days it was stable.

What do you think about just adding a section to the never page that explains that it is only valid in function return type positions?

Otherwise, I would think #206 should be reverted, and the grammar updated so that function return types are _Type_ | !.

Also, it looks like there was some discussion on that PR about retaining the information about divergence (and #271), but that never happened?

src/paths.md

Havvy

I'd rather not have each page be types/whatever-type.html repeating the word "type". It just makes typing the URL manually difficult. Although I may be of the rare breed who actually does that.

Havvy · 2018-10-23T05:36:30Z

src/types-redirect.html

@@ -0,0 +1,41 @@
+<script>


This is nice. I usually don't think about the disruption of moving all the information around. I'd rather this be done via an mdbook plugin, but since that plugin doesn't exist, this is fine. Speaking of which, we really need to update our books to mdbook 0.2.x.

Is it correct that all the books will need to upgraded to 0.2 at the same time? Otherwise, I imagine the rust-lang/rust "rustbook" tool would need to handle both versions, which sounds troublesome.

I'd be happy to help make that happen. I feel like it would be best to make a tool to automatically update the books to make life easier.

ehuss · 2018-10-23T16:05:20Z

I'd rather not have each page be types/whatever-type.html repeating the word "type".

No problem, I was just mimicking the expression pages.

matthewjasper

Nice! I've left some comments but a lot of these are preexisting, so feel to ignore those that are.

matthewjasper · 2018-10-17T11:06:50Z

src/types.md

+    * [Boolean] — `true` or `false`
+    * [Numeric] — integer and float
+    * [Textual] — `char` and `str`
+    * [Never] — `!` — a type with no value


matthewjasper · 2018-10-17T11:07:13Z

src/types.md

+    * [Trait objects]
+    * [Impl trait]
+
+


double blank line

matthewjasper · 2018-10-17T11:10:27Z

src/types.md

 boundary applies, so the use of parentheses is required. Grammar rules that
 require this disambiguation use the [_TypeNoBounds_] rule instead of
 [_Type_].

-
 ```rust
 # use std::any::Any;
 type T<'a> = &'a(Any + Send);


add a space before (, use dyn

matthewjasper · 2018-10-20T09:43:09Z

src/types.md

-
-## Self types
-
-The special type `Self` has a meaning within traits and implementations: it


Was this removed?

It was merged with the discussion of Self on the paths page.

matthewjasper · 2018-10-20T09:43:39Z

src/types.md

@@ -768,7 +111,8 @@ let x: Vec<_> = (0..10).collect();
  There should be a broader discussion of type inference somewhere.
 -->

-## Type parameters
+
+### Type parameters


This should be on its own page

What do you think about moving it to items/generics.md. It seems like it would be natural for it to live there.

No, I would prefer them to live with all of the other types.

I feel like it would be inconsistent to do that. Currently everything that was moved to a separate page is an actual type. To me, type parameters are not types themselves (they don't have a defined meaning on their own). Similar to Self and _, they are things that can be resolved into an actual type.

Perhaps it could be moved as a second-level page under "Type System"? The same question could be applied to Inferred type which probably equally deserves to be separate (considering it probably needs a lot more detail and examples).

They don't resolve to an actual type until monomorphisation, so for almost all of compilation they are their own types with their own rules.

Either way, I'm happy to merge this as is once it has been rebased (again -_-).

ok, I agree! 😄 I went ahead and moved the inferred type to its own page, too, since I foresee that potentially getting long by itself. It's not too hard to move these around, and with the redirects it hopefully isn't too disruptive (although it's a little rough on outstanding PRs).

matthewjasper · 2018-10-23T21:16:19Z

src/types/array.md

+An array is a fixed-size sequence of `N` elements of type `T`. The array type
+is written as `[T; N]`.
+
+An array can be allocated on either the stack or the heap. The size is an


This sentence can be removed, and the two paragraphs merged.

matthewjasper · 2018-10-23T21:17:02Z

src/types/array.md

+let boxed_array: Box<[i32]> = Box::new([1, 2, 3]);
+```
+
+All elements of arrays are always initialized, and access to an array is


I guess this should now say something like "array elements may only be moved from by slice patterns".

I'm not sure exactly what you mean here. In general it seems like a lot more can be said, though.

matthewjasper · 2018-10-23T21:19:28Z

src/types/function-pointer.md

+
+A function pointer type consists of a possibly-empty set of function-type
+modifiers (such as `unsafe` or `extern`), a sequence of input types and an
+output type.


Can we remove places where we say what's already in the Syntax? This should either explain what unsafe or extern do, or not be here at all.

I agree. There are quite a few places that I neglected to remove the prose description of the syntax. I'll leave that on my todo list.

matthewjasper · 2018-10-23T21:19:54Z

src/types/numeric.md

+
+* The unsigned word types `u8`, `u16`, `u32`, `u64`, and `u128` with values
+  drawn from the integer intervals [0, 2^8 - 1], [0, 2^16 - 1], [0, 2^32 - 1],
+  [0, 2^64 - 1], and [0, 2^128 - 1] respectively.


These should use <sup> tags. They also should be in a table.

ehuss · 2018-10-23T22:39:21Z

Made a few updates. I don't mind making a few content edits, but I don't want to get too bogged down on rewriting things. A lot of these pages are very bare and will probably need significant work (probably by someone more qualified than me).

matthewjasper · 2018-11-03T12:50:13Z

This needs rebasing

ehuss · 2018-11-03T18:11:51Z

This needs rebasing

Rebased.

This splits the types chapter into multiple subchapters. I tried to avoid content changes, but I ended up with a few changes: - Added overview links in `types.md`, and a separate discussion of type expressions. - Split array and slice into separate chapters. Although there is some overlap between them, I feel like it was awkward explaining one and then the other. I also felt it conflated the two too much since slices can be used for more than arrays. - Combined `Self` section with the one on the paths page. - Added a basic redirector for external links. Some pages may seem a little bare now, but I think each type page has potential to be expanded and improved in the future.

matthewjasper · 2018-11-05T21:14:39Z

Thanks!

Havvy reviewed Oct 23, 2018

View reviewed changes

src/paths.md Outdated Show resolved Hide resolved

Havvy reviewed Oct 23, 2018

View reviewed changes

ehuss force-pushed the split-types branch 2 times, most recently from 89059b2 to 7166c5f Compare October 23, 2018 15:53

matthewjasper reviewed Oct 23, 2018

View reviewed changes

ehuss force-pushed the split-types branch from 87b4c6e to 91b928b Compare November 3, 2018 17:58

ehuss added 3 commits November 4, 2018 18:01

Minor review edits.

18f1418

Move Inferred Types and Type Parameters to their own pages.

eb02dd5

ehuss force-pushed the split-types branch from 91b928b to eb02dd5 Compare November 5, 2018 02:17

matthewjasper approved these changes Nov 5, 2018

View reviewed changes

matthewjasper merged commit 5aafa12 into rust-lang:master Nov 5, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Split Types Chapter #454

Split Types Chapter #454

ehuss commented Oct 17, 2018 •

edited

Loading

ehuss commented Oct 17, 2018

Havvy Oct 23, 2018

ehuss Oct 23, 2018

Havvy left a comment

Havvy Oct 23, 2018

ehuss Oct 23, 2018

ehuss commented Oct 23, 2018

matthewjasper left a comment

matthewjasper Oct 17, 2018

matthewjasper Oct 17, 2018

matthewjasper Oct 17, 2018

matthewjasper Oct 20, 2018

ehuss Oct 23, 2018

matthewjasper Oct 20, 2018

ehuss Oct 23, 2018

matthewjasper Oct 25, 2018

ehuss Nov 3, 2018

matthewjasper Nov 3, 2018

ehuss Nov 5, 2018

matthewjasper Oct 23, 2018

matthewjasper Oct 23, 2018

ehuss Oct 23, 2018

matthewjasper Oct 23, 2018

ehuss Oct 23, 2018

matthewjasper Oct 23, 2018

ehuss commented Oct 23, 2018

matthewjasper commented Nov 3, 2018

ehuss commented Nov 3, 2018

matthewjasper commented Nov 5, 2018


		## Self types

		The special type `Self` has a meaning within traits and implementations: it

Split Types Chapter #454

Split Types Chapter #454

Conversation

ehuss commented Oct 17, 2018 • edited Loading

ehuss commented Oct 17, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Havvy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ehuss commented Oct 23, 2018

matthewjasper left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ehuss commented Oct 23, 2018

matthewjasper commented Nov 3, 2018

ehuss commented Nov 3, 2018

matthewjasper commented Nov 5, 2018

ehuss commented Oct 17, 2018 •

edited

Loading