From 8a8cccd4b60d85498c99c14141a1dab1c9e5cf5a Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Fri, 6 Dec 2013 01:26:49 -0500 Subject: [PATCH 01/21] Explain potentially confusing string example. Reported be @ElBaha --- doc/tutorial.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index 58bfd047d95..dee1f1334ef 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -207,14 +207,15 @@ let hi = "hi"; let mut count = 0; while count < 10 { - println!("count: {}", count); + println!("count is {}", count); count += 1; } ~~~~ -Although Rust can almost always infer the types of local variables, you -can specify a variable's type by following it with a colon, then the type -name. Static items, on the other hand, always require a type annotation. +Although Rust can almost always infer the types of local variables, you can +specify a variable's type by following it in the `let` with a colon, then the +type name. Static items, on the other hand, always require a type annotation. + ~~~~ static MONSTER_FACTOR: f64 = 57.8; From 61e8268645b13dfe507827b85414e60960670916 Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Fri, 6 Dec 2013 02:12:15 -0500 Subject: [PATCH 02/21] Fix span. --- doc/tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index dee1f1334ef..683121729c8 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -141,7 +141,7 @@ an error message like this: ~~~~ {.notrust} hello.rs:2:4: 2:16 error: unresolved name: print_with_unicorns hello.rs:2 print_with_unicorns("hello?"); - ^~~~~~~~~~~~~~~~~~~~~~~ + ^~~~~~~~~~~~~~~~~~~ ~~~~ In its simplest form, a Rust program is a `.rs` file with some types From 8ae340a026b734b390400655f7c155e553f720ff Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Fri, 6 Dec 2013 02:13:49 -0500 Subject: [PATCH 03/21] Note that Rust can be embedded. --- doc/tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index 683121729c8..4553588a267 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -149,7 +149,7 @@ and functions defined in it. If it has a `main` function, it can be compiled to an executable. Rust does not allow code that's not a declaration to appear at the top level of the file: all statements must live inside a function. Rust programs can also be compiled as -libraries, and included in other programs. +libraries, and included in other programs, even ones not written in Rust. ## Editing Rust code From d86f8b2fcab4ef70283d13982aa18cec6f66ec4f Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Fri, 6 Dec 2013 02:25:01 -0500 Subject: [PATCH 04/21] Add a link to the wiki's package list and refer to git --- doc/tutorial.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index 4553588a267..94686cf7c84 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -57,9 +57,13 @@ they don't contain references to names that aren't actually defined. # Getting started -The Rust compiler currently must be built from a [tarball], unless you -are on Windows, in which case using the [installer][win-exe] is -recommended. +> **NOTE**: The tarball and installer links are for the most recent release, +> not master. + +The Rust compiler currently must be built from a [tarball] or [git], unless +you are on Windows, in which case using the [installer][win-exe] is +recommended. There is a list of community-maintained nightly builds and +packages [on the wiki][wiki-packages]. Since the Rust compiler is written in Rust, it must be built by a precompiled "snapshot" version of itself (made in an earlier state @@ -84,6 +88,7 @@ supported build environments that are most likely to work. [bug-3319]: https://github.com/mozilla/rust/issues/3319 [wiki-start]: https://github.com/mozilla/rust/wiki/Note-getting-started-developing-Rust +[git]: https://github.com/mozilla/rust.git To build from source you will also need the following prerequisite packages: @@ -163,6 +168,9 @@ Sublime Text 2, available both [standalone][sublime] and through [Sublime Package Control][sublime-pkg], and support for Kate under `src/etc/kate`. +A community-maintained list of available Rust tooling is [on the +wiki][wiki-packages]. + There is ctags support via `src/etc/ctags.rust`, but many other tools and editors are not yet supported. If you end up writing a Rust mode for your favorite editor, let us know so that we can link to it. @@ -3258,4 +3266,4 @@ There is further documentation on the [wiki], however those tend to be even more [rustpkg]: tutorial-rustpkg.html [wiki]: https://github.com/mozilla/rust/wiki/Docs - +[wiki-packages]: https://github.com/mozilla/rust/wiki/Doc-packages,-editors,-and-other-tools From 039a5933fb350dda5263cce824f7da8b86c473df Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Fri, 6 Dec 2013 02:25:55 -0500 Subject: [PATCH 05/21] Fix grammar error. --- doc/tutorial.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index 94686cf7c84..624d5528424 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -3255,7 +3255,8 @@ tutorials on individual topics. * [Error-handling and Conditions][conditions] * [Packaging up Rust code][rustpkg] -There is further documentation on the [wiki], however those tend to be even more out of date as this document. +There is further documentation on the [wiki], however those tend to be even +more out of date than this document. [borrow]: tutorial-borrowed-ptr.html [tasks]: tutorial-tasks.html From 94e0a03f5d1d27d34d97c691964c1ff9b5cab086 Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Fri, 6 Dec 2013 11:29:58 -0500 Subject: [PATCH 06/21] Add rustdoc documentation. --- doc/rustdoc.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/tutorial.md | 8 +++--- mk/docs.mk | 7 +++++ 3 files changed, 84 insertions(+), 3 deletions(-) create mode 100644 doc/rustdoc.md diff --git a/doc/rustdoc.md b/doc/rustdoc.md new file mode 100644 index 00000000000..29ac2d2a2f3 --- /dev/null +++ b/doc/rustdoc.md @@ -0,0 +1,72 @@ +% Rust Documentation + +`rustdoc` is the built-in tool for generating documentation. It integrates +with the compiler to provide accurate hyperlinking between usage of types and +their documentation. Furthermore, by not using a separate parser, it will +never reject your valid Rust code. + +# Creating Documentation + +Documenting Rust APIs is quite simple. To document a given item, we have "doc +comments": + +~~~ +// the "link" crate attribute is currently required for rustdoc, but normally +// isn't needed. +#[link(name="universe")]; +#[crate_type="lib"]; + +//! Tools for dealing with universes (this is a doc comment, and is shown on +//! the crate index page. The ! makes it apply to the parent of the comment, +//! rather than what follows). + +/// Widgets are very common (this is a doc comment, and will show up on +/// Widget's documentation). +pub struct Widget { + /// All widgets have a purpose (this is a doc comment, and will show up + /// the field's documentation). + purpose: ~str, + /// Humans are not allowed to understand some widgets + understandable: bool +} + +pub fn recalibrate() { + //! Recalibrate a pesky universe (this is also a doc comment, like above, + //! the documentation will be applied to the *parent* item, so + //! `recalibrate`). + /* ... */ +} +~~~ + +Then, one can run `rustdoc universe.rs`. By default, it generates a directory +called `doc`, with the documentation for `universe` being in +`doc/universe/index.html`. If you are using other crates with `extern mod`, +rustdoc will even link to them when you use their types, as long as their +documentation has already been generated by a previous run of rustdoc, or the +crate advertises that its documentation is hosted at a given URL. + +The generated output can be controlled with the `doc` crate attribute, which +is how the above advertisement works. An example from the `libstd` +documentation: + +~~~ +#[doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk.png", + html_favicon_url = "http://www.rust-lang.org/favicon.ico", + html_root_url = "http://static.rust-lang.org/doc/master")]; +~~~ + +The `html_root_url` is the prefix that rustdoc will apply to any references to +that crate's types etc. + +rustdoc can also generate JSON, for consumption by other tools, with +`rustdoc --output-format json`, and also consume already-generated JSON with +`rustdoc --input-format json`. + +# Using the Documentation + +The web pages generated by rustdoc present the same logical heirarchy that one +writes a library with. Every kind of item (function, struct, etc) has its own +color, and one can always click on a colored type to jump to its +documentation. There is a search bar at the top, which is powered by some +javascript and a statically-generated search index. No special web server is +required for the search. diff --git a/doc/tutorial.md b/doc/tutorial.md index 624d5528424..f8e81ae8722 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -872,9 +872,9 @@ A *destructor* is a function responsible for cleaning up the resources used by an object when it is no longer accessible. Destructors can be defined to handle the release of resources like files, sockets and heap memory. -Objects are never accessible after their destructor has been called, so there -are no dynamic failures from accessing freed resources. When a task fails, the -destructors of all objects in the task are called. +Objects are never accessible after their destructor has been called, so no +dynamic failures are possible from accessing freed resources. When a task +fails, destructors of all objects in the task are called. The `~` sigil represents a unique handle for a memory allocation on the heap: @@ -3254,6 +3254,7 @@ tutorials on individual topics. * [Containers and iterators][container] * [Error-handling and Conditions][conditions] * [Packaging up Rust code][rustpkg] +* [Documenting Rust code][rustdoc] There is further documentation on the [wiki], however those tend to be even more out of date than this document. @@ -3265,6 +3266,7 @@ more out of date than this document. [container]: tutorial-container.html [conditions]: tutorial-conditions.html [rustpkg]: tutorial-rustpkg.html +[rustdoc]: tutorial-rustdoc.html [wiki]: https://github.com/mozilla/rust/wiki/Docs [wiki-packages]: https://github.com/mozilla/rust/wiki/Doc-packages,-editors,-and-other-tools diff --git a/mk/docs.mk b/mk/docs.mk index 412981add6c..43b7e9e3099 100644 --- a/mk/docs.mk +++ b/mk/docs.mk @@ -74,6 +74,13 @@ doc/rustpkg.html: rustpkg.md doc/version_info.html doc/rust.css \ $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \ $(CFG_PANDOC) $(HTML_OPTS) --output=$@ +DOCS += doc/rustdoc.html +doc/rustdoc.html: rustdoc.md doc/version_info.html doc/rust.css \ + doc/favicon.inc + @$(call E, pandoc: $@) + $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \ + $(CFG_PANDOC) $(HTML_OPTS) --output=$@ + DOCS += doc/tutorial.html doc/tutorial.html: tutorial.md doc/version_info.html doc/rust.css \ doc/favicon.inc From b6cf5f5af11b06fa117c4398c7727538ddcf0391 Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Fri, 6 Dec 2013 12:09:07 -0500 Subject: [PATCH 07/21] Fix tiny formatting error. --- doc/tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index f8e81ae8722..ac559ae69b7 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -335,7 +335,7 @@ let d = 1000i32; // d is an i32 There are two floating-point types: `f32`, and `f64`. Floating-point numbers are written `0.0`, `1e6`, or `2.1e-4`. Like integers, floating-point literals are inferred to the correct type. -Suffixes ``f32`, and `f64` can be used to create literals of a specific type. +Suffixes `f32`, and `f64` can be used to create literals of a specific type. The keywords `true` and `false` produce literals of type `bool`. From d00a407e00a28a3607ff363cfcc1166eb4559673 Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Fri, 6 Dec 2013 12:09:22 -0500 Subject: [PATCH 08/21] Clarify that strings aren't magical. --- doc/tutorial.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index ac559ae69b7..1e9b64c9e22 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -343,7 +343,8 @@ Characters, the `char` type, are four-byte Unicode codepoints, whose literals are written between single quotes, as in `'x'`. Just like C, Rust understands a number of character escapes, using the backslash character, such as `\n`, `\r`, and `\t`. String literals, -written between double quotes, allow the same escape sequences. +written between double quotes, allow the same escape sequences, and do no +other processing, unlike languages such as PHP or shell. On the other hand, raw string literals do not process any escape sequences. They are written as `r##"blah"##`, with a matching number of zero or more `#` From 0f82cbd19a0bd2d0d5e91c2fc807c7af21288eb4 Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Fri, 6 Dec 2013 12:09:54 -0500 Subject: [PATCH 09/21] Clarify `as`, mention transmute. --- doc/tutorial.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index 1e9b64c9e22..14dfc884122 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -361,17 +361,19 @@ Rust's set of operators contains very few surprises. Arithmetic is done with also a unary prefix operator that negates numbers. As in C, the bitwise operators `>>`, `<<`, `&`, `|`, and `^` are also supported. -Note that, if applied to an integer value, `!` flips all the bits (like `~` in -C). +Note that, if applied to an integer value, `!` flips all the bits (bitwise +NOT, like `~` in C). The comparison operators are the traditional `==`, `!=`, `<`, `>`, `<=`, and `>=`. Short-circuiting (lazy) boolean operators are written `&&` (and) and `||` (or). -For type casting, Rust uses the binary `as` operator. It takes an -expression on the left side and a type on the right side and will, -if a meaningful conversion exists, convert the result of the -expression to the given type. +For compile-time type casting, Rust uses the binary `as` operator. It takes +an expression on the left side and a type on the right side and will, if a +meaningful conversion exists, convert the result of the expression to the +given type. Generally, `as` is only used with the primitive numeric types or +pointers, and is not overloadable. [`transmute`][transmute] can be used for +unsafe C-like casting of same-sized types. ~~~~ let x: f64 = 4.0; @@ -379,6 +381,8 @@ let y: uint = x as uint; assert!(y == 4u); ~~~~ +[transmute]: http://static.rust-lang.org/doc/master/std/cast/fn.transmute.html + ## Syntax extensions *Syntax extensions* are special forms that are not built into the language, From eb8739f4f868cfb52bc4bb3500bb895d5e4c6032 Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Fri, 6 Dec 2013 12:10:10 -0500 Subject: [PATCH 10/21] Fix tiny formatting error. --- doc/tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index 14dfc884122..6f6a86042f3 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -393,7 +393,7 @@ useful of which is [`format!`][fmt], a `sprintf`-like text formatter that you will often see in examples, and its related family of macros: `print!`, `println!`, and `write!`. -`format!` draws syntax from python, but contains many of the same principles +`format!` draws syntax from Python, but contains many of the same principles that [printf][pf] has. Unlike printf, `format!` will give you a compile-time error when the types of the directives don't match the types of the arguments. From 079ea00d238113827c0c2d57e8447ce1ab69afe9 Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Fri, 6 Dec 2013 12:10:20 -0500 Subject: [PATCH 11/21] Macro definition is feature gated. --- doc/tutorial.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index 6f6a86042f3..7b8c670e8ea 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -410,7 +410,9 @@ println!("what is this thing: {:?}", mystery_object); [pf]: http://en.cppreference.com/w/cpp/io/c/fprintf [fmt]: http://static.rust-lang.org/doc/master/std/fmt/index.html -You can define your own syntax extensions with the macro system. For details, see the [macro tutorial][macros]. +You can define your own syntax extensions with the macro system. For details, +see the [macro tutorial][macros]. Note that macro definition is currently +considered an unstable feature. # Control structures From f006a10b1eed27fc03b89ed2bb34202eb7e412e7 Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Fri, 6 Dec 2013 12:10:36 -0500 Subject: [PATCH 12/21] Wildcard changes. --- doc/tutorial.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index 7b8c670e8ea..6abbc15d96e 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -473,9 +473,8 @@ their own value. A single arm may match multiple different patterns by combining them with the pipe operator (`|`), so long as every pattern binds the same set of variables. Ranges of numeric literal patterns can be expressed with two dots, as in `M..N`. The underscore (`_`) is -a wildcard pattern that matches any single value. The asterisk (`*`) -is a different wildcard that can match one or more fields in an `enum` -variant. +a wildcard pattern that matches any single value. (`..`) is a different +wildcard that can match one or more fields in an `enum` variant. The patterns in a match arm are followed by a fat arrow, `=>`, then an expression to evaluate. Each case is separated by commas. It's often From 381c08bf69374c41d696b4892f4c06139289caca Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Fri, 6 Dec 2013 12:11:11 -0500 Subject: [PATCH 13/21] loop -> continue --- doc/tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index 6abbc15d96e..a430c6c72ec 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -546,7 +546,7 @@ literals and most `enum` variants. `while` denotes a loop that iterates as long as its given condition (which must have type `bool`) evaluates to `true`. Inside a loop, the -keyword `break` aborts the loop, and `loop` aborts the current +keyword `break` aborts the loop, and `continue` aborts the current iteration and continues with the next. ~~~~ From 2750adb5d8eb37906a568b99755847c25fe5e59a Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Fri, 6 Dec 2013 12:11:28 -0500 Subject: [PATCH 14/21] Inherited mutabilty clarification Also no longer reference mutable fields --- doc/tutorial.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index a430c6c72ec..7ddb63fd914 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -590,9 +590,8 @@ struct Point { } ~~~~ -Inherited mutability means that any field of a struct may be mutable, if the -struct is in a mutable slot (or a field of a struct in a mutable slot, and -so forth). +Structs have "inherited mutability", which means that any field of a struct +may be mutable, if the struct is in a mutable slot. With a value (say, `mypoint`) of such a type in a mutable location, you can do `mypoint.y += 1.0`. But in an immutable location, such an assignment to a From d9eff8de8a8455875dea40a3630856c9326bd576 Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Fri, 6 Dec 2013 12:12:11 -0500 Subject: [PATCH 15/21] Clarify arity --- doc/tutorial.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index 7ddb63fd914..f10275cc351 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -753,9 +753,9 @@ fn area(sh: Shape) -> f64 { ## Tuples -Tuples in Rust behave exactly like structs, except that their fields -do not have names. Thus, you cannot access their fields with dot notation. -Tuples can have any arity except for 0 (though you may consider +Tuples in Rust behave exactly like structs, except that their fields do not +have names. Thus, you cannot access their fields with dot notation. Tuples +can have any arity (number of elements) except for 0 (though you may consider unit, `()`, as the empty tuple if you like). ~~~~ From b5122c52aefd05d4485864b2b6e01f41ddfbc483 Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Fri, 6 Dec 2013 12:13:00 -0500 Subject: [PATCH 16/21] Clarify newtype --- doc/tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index f10275cc351..5bd0d35895e 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -803,7 +803,7 @@ let id_int: int = *my_gizmo_id; ~~~~ Types like this can be useful to differentiate between data that have -the same type but must be used in different ways. +the same underlying type but must be used in different ways. ~~~~ struct Inches(int); From 888144c98d43d62e839307219346398660ddf546 Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Fri, 6 Dec 2013 12:13:10 -0500 Subject: [PATCH 17/21] Function declaration takes pats, not exprs. --- doc/tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index 5bd0d35895e..7478e5a70f7 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -820,7 +820,7 @@ declarations, such as `type`, functions can be declared both at the top level and inside other functions (or in modules, which we'll come back to [later](#crates-and-the-module-system)). The `fn` keyword introduces a function. A function has an argument list, which is a parenthesized -list of `expr: type` pairs separated by commas. An arrow `->` +list of `name: type` pairs separated by commas. An arrow `->` separates the argument list and the function's return type. ~~~~ From a44852a2d5ac12545a3c1b55dab1c3d4070872a1 Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Tue, 10 Dec 2013 09:25:36 -0500 Subject: [PATCH 18/21] Update Owned to Send, show some types which aren't --- doc/tutorial.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index 7478e5a70f7..f6895adff06 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -922,11 +922,15 @@ let mut b = Foo { x: 5, y: ~10 }; b.x = 10; ~~~~ -If an object doesn't contain garbage-collected boxes, it consists of a single -ownership tree and is given the `Owned` trait which allows it to be sent +If an object doesn't contain any non-Send types, it consists of a single +ownership tree and is itself given the `Send` trait which allows it to be sent between tasks. Custom destructors can only be implemented directly on types -that are `Owned`, but garbage-collected boxes can still *contain* types with -custom destructors. +that are `Send`, but non-`Send` types can still *contain* types with custom +destructors. Example of types which are not `Send` are [`Gc`][gc] and +[`Rc`][rc], the shared-ownership types. + +[gc]: http://static.rust-lang.org/doc/master/std/gc/struct.Gc.html +[rc]: http://static.rust-lang.org/doc/master/std/rc/struct.Rc.html # Implementing a linked list From fab5624eb6373d529f21309380ea467a8b4b5664 Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Tue, 10 Dec 2013 09:26:11 -0500 Subject: [PATCH 19/21] Tiny fixes to linked list section. --- doc/tutorial.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index f6895adff06..74a02a12023 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -1235,8 +1235,9 @@ xs = prepend::(xs, 15); xs = prepend::(xs, 20); ~~~ -In the type grammar, the language uses `Type` to describe a list of -type parameters, but expressions use `identifier::`. +In declarations, the language uses `Type` to describe a list of type +parameters, but expressions use `identifier::`, to disambiguate the +`<` operator. ## Defining list equality with generics @@ -1313,7 +1314,7 @@ provide. In uncommon cases, the indirection can provide a performance gain or memory reduction by making values smaller. However, unboxed values should almost -always be preferred. +always be preferred when they are usable. Note that returning large unboxed values via boxes is unnecessary. A large value is returned via a hidden output parameter, and the decision on where to @@ -1324,7 +1325,7 @@ fn foo() -> (u64, u64, u64, u64, u64, u64) { (5, 5, 5, 5, 5, 5) } -let x = ~foo(); // allocates, and writes the integers directly to it +let x = ~foo(); // allocates a ~ box, and writes the integers directly to it ~~~~ Beyond the properties granted by the size, an owned box behaves as a regular @@ -1403,7 +1404,7 @@ compute_distance(managed_box, owned_box); Here the `&` operator is used to take the address of the variable `on_the_stack`; this is because `on_the_stack` has the type `Point` (that is, a struct value) and we have to take its address to get a -value. We also call this _borrowing_ the local variable +reference. We also call this _borrowing_ the local variable `on_the_stack`, because we are creating an alias: that is, another route to the same data. From c8f47db8f54b78c917feb9729e3a30a870207fbf Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Tue, 10 Dec 2013 09:26:43 -0500 Subject: [PATCH 20/21] Update `Freeze` information --- doc/tutorial.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index 74a02a12023..cea91d1f24f 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -1431,7 +1431,8 @@ For a more in-depth explanation of borrowed pointers, read the ## Freezing Lending an immutable pointer to an object freezes it and prevents mutation. -`Owned` objects have freezing enforced statically at compile-time. +`Freeze` objects have freezing enforced statically at compile-time. Examples +of non-`Freeze` types are `@mut` and [`RefCell`][refcell]. ~~~~ let mut x = 5; @@ -1456,6 +1457,8 @@ let y = x; // the box is now unfrozen again ~~~~ +[refcell]: http://static.rust-lang.org/doc/master/std/cell/struct.RefCell.html + # Dereferencing pointers Rust uses the unary star operator (`*`) to access the contents of a From c935a88a971f3b1e988e74182a3d8bba869fabbe Mon Sep 17 00:00:00 2001 From: Corey Richardson Date: Tue, 10 Dec 2013 09:27:02 -0500 Subject: [PATCH 21/21] Remove duplication of libstd docs. This is literally a copy-paste, there's no need to have this duplication. --- doc/tutorial.md | 54 +++++-------------------------------------------- 1 file changed, 5 insertions(+), 49 deletions(-) diff --git a/doc/tutorial.md b/doc/tutorial.md index cea91d1f24f..ae045581ad3 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -3196,59 +3196,15 @@ Both auto-insertions can be disabled with an attribute if necessary: #[no_implicit_prelude]; ~~~ -## The standard library in detail +See the [API documentation][stddoc] for details. -The Rust standard library provides runtime features required by the language, -including the task scheduler and memory allocators, as well as library -support for Rust built-in types, platform abstractions, and other commonly -used features. - -[`std`] includes modules corresponding to each of the integer types, each of -the floating point types, the [`bool`] type, [tuples], [characters], [strings], -[vectors], [managed boxes], [owned boxes], -and unsafe and borrowed [pointers]. Additionally, `std` provides -some pervasive types ([`option`] and [`result`]), -[task] creation and [communication] primitives, -platform abstractions ([`os`] and [`path`]), basic -I/O abstractions ([`io`]), [containers] like [`hashmap`], -common traits ([`kinds`], [`ops`], [`cmp`], [`num`], -[`to_str`], [`clone`]), and complete bindings to the C standard library ([`libc`]). - -The full documentation for `std` can be found here: [standard library]. - -[standard library]: std/index.html -[`std`]: std/index.html -[`bool`]: std/bool/index.html -[tuples]: std/tuple/index.html -[characters]: std/char/index.html -[strings]: std/str/index.html -[vectors]: std/vec/index.html -[managed boxes]: std/managed/index.html -[owned boxes]: std/owned/index.html -[pointers]: std/ptr/index.html -[`option`]: std/option/index.html -[`result`]: std/result/index.html -[task]: std/task/index.html -[communication]: std/comm/index.html -[`os`]: std/os/index.html -[`path`]: std/path/index.html -[`io`]: std/io/index.html -[containers]: std/container/index.html -[`hashmap`]: std/hashmap/index.html -[`kinds`]: std/kinds/index.html -[`ops`]: std/ops/index.html -[`cmp`]: std/cmp/index.html -[`num`]: std/num/index.html -[`to_str`]: std/to_str/index.html -[`clone`]: std/clone/index.html -[`libc`]: std/libc/index.html +[stddoc]: std/index.html ## The extra library -Rust also ships with the [extra library], an accumulation of -useful things, that are however not important enough -to deserve a place in the standard library. -You can use them by linking to `extra` with an `extern mod extra;`. +Rust also ships with the [extra library], an accumulation of useful things, +that are however not important enough to deserve a place in the standard +library. You can use them by linking to `extra` with an `extern mod extra;`. [extra library]: extra/index.html