Merge pull request #7270 from thestinger/doc

accumulated doc pull requests from the queue

Author: thestinger

AUTHORS.txt

@@ -10,9 +10,11 @@ Aleksander Balicki <[email protected]>
 Alex Crichton <[email protected]>
 Alex Rønne Petersen <[email protected]>
 Alexander Stavonin <[email protected]>
+Alexei Sholik <[email protected]>
 Andreas Gal <[email protected]>
 Andrew Dunham <[email protected]>
 Andrew Paseltiner <[email protected]>
+Anthony Juckel <[email protected]>
 Arkaitz Jimenez <[email protected]>
 Armin Ronacher <[email protected]>
 Ashok Gautham <[email protected]>
@@ -29,23 +31,32 @@ Benjamin Kircher <[email protected]>
 Benjamin Peterson <[email protected]>
 Bilal Husain <[email protected]>
 Bill Fallon <[email protected]>
+Bill Myers <[email protected]>
+Bill Wendling <[email protected]>
+Björn Steinbrink <[email protected]>
 Brendan Eich <[email protected]>
 Brendan Zabarauskas <[email protected]>
 Brett Cannon <[email protected]>
 Brian Anderson <[email protected]>
 Brian J. Burg <[email protected]>
 Brian Leibig <[email protected]>
+Bryan Dunsmore <[email protected]>
+Caitlin Potter <[email protected]>
 Chris Double <[email protected]>
 Chris Peterson <[email protected]>
 Chris Pressey <[email protected]>
 Cody Schroeder <[email protected]>
+Corey Richardson <[email protected]>
 Damian Gryski <[email protected]>
 Damien Grassart <[email protected]>
 Damien Schoof <[email protected]>
 Daniel Brooks <[email protected]>
+Daniel Farina <[email protected]>
+Dan Luu <[email protected]>
 Daniel Luz <[email protected]>
 Daniel Micay <[email protected]>
 Daniel Patterson <[email protected]>
+Daniel Ralston <[email protected]>
 Daniel Ursache Dogariu <[email protected]>
 Dave Herman <[email protected]>
 David Forsythe <[email protected]>
@@ -62,17 +73,21 @@ Eric Holmes <[email protected]>
 Erick Tryzelaar <[email protected]>
 Erik Rose <[email protected]>
 Evan McClanahan <[email protected]>
+Fedor Indutny <[email protected]>
 Felix S. Klock II <[email protected]>
 Francisco Souza <[email protected]>
 Franklin Chen <[email protected]>
+Gábor Horváth <[email protected]>
 Gabriel <[email protected]>
 Gareth Daniel Smith <[email protected]>
+gifnksm <[email protected]>
 Glenn Willen <[email protected]>
 Gonçalo Cabrita <[email protected]>
 Graham Fawcett <[email protected]>
 Grahame Bowland <[email protected]>
 Haitao Li <[email protected]>
 hansjorg <[email protected]>
+Herman J. Radtke III <[email protected]>
 Huon Wilson <[email protected]>
 Ian D. Bollinger <[email protected]>
 Ilyong Cho <[email protected]>
@@ -83,6 +98,7 @@ Jacob Harris Cryer Kragh <[email protected]>
 Jacob Parker <[email protected]>
 Jakub Wieczorek <[email protected]>
 James Miller <[email protected]>
+James Tranovich <[email protected]>
 Jason Orendorff <[email protected]>
 Jed Davis <[email protected]>
 Jeff Balogh <[email protected]>
@@ -92,6 +108,7 @@ Jeffrey Yasskin <[email protected]>
 Jeong YunWon <[email protected]>
 Jens Nockert <[email protected]>
 Jesse Jones <[email protected]>
+Jesse Luehrs <[email protected]>
 Jesse Ruderman <[email protected]>
 Jihyun Yu <[email protected]>
 Jim Blandy <[email protected]>
@@ -104,14 +121,18 @@ Jonathan Sternberg <[email protected]>
 Josh Matthews <[email protected]>
 Joshua Clark <[email protected]>
 Joshua Wise <[email protected]>
+Junyoung Cho <[email protected]>
 Jyun-Yan You <[email protected]>
 Kang Seonghoon <[email protected]>
 Kelly Wilson <[email protected]>
 Kevin Atkinson <[email protected]>
+Kevin Ballard <[email protected]>
 Kevin Cantu <[email protected]>
+klutzy <[email protected]>
 Kyeongwoon Lee <[email protected]>
 Laurent Bonnans <[email protected]>
 Lawrence Velázquez <[email protected]>
+Leah Hanson <[email protected]>
 Lennart Kudling <[email protected]>
 Lindsey Kuper <[email protected]>
 Luca Bruno <[email protected]>
@@ -122,6 +143,7 @@ Margaret Meyerhofer <[email protected]>
 Marijn Haverbeke <[email protected]>
 Mark Lacey <[email protected]>
 Mark Vian <[email protected]>
+Marti Raudsepp <[email protected]>
 Martin DeMello <[email protected]>
 Marvin Löbel <[email protected]>
 Matt Brubeck <[email protected]>
@@ -143,43 +165,64 @@ Patrick Walton <[email protected]>
 Patrik Kårlin <[email protected]>
 Paul Stansifer <[email protected]>
 Paul Woolcock <[email protected]>
+Pavel Panchekha <[email protected]>
 Peter Hull <[email protected]>
 Peter Williams <[email protected]>
 Philipp Brüschweiler <[email protected]>
 Rafael Ávila de Espíndola <[email protected]>
+Ralph Bodenner <[email protected]>
 Ralph Giles <[email protected]>
+Ramkumar Ramachandra <[email protected]>
 Reuben Morais <[email protected]>
 Rick Waldron <[email protected]>
 Rob Arnold <[email protected]>
+Rob Hoelz <[email protected]>
 Roland Tanglao <[email protected]>
+Ron Dahlgren <[email protected]>
 Roy Frostig <[email protected]>
 Ryan Scheel <[email protected]>
+Samuel Chase <[email protected]>
+Sander Mathijs van Veen <[email protected]>
+Sangeun Kim <[email protected]>
+Saurabh Anand <[email protected]>
+Sean Moon <[email protected]>
 Sean Stangl <[email protected]>
 Sebastian N. Fernandez <[email protected]>
 Seth Pink <[email protected]>
 Seo Sanghyeon <[email protected]>
 sevrak <[email protected]>
+SiegeLord <[email protected]>
 Simon Barber-Dueck <[email protected]>
 Simon Sapin <[email protected]>
 startling <[email protected]>
 Stefan Plantikow <[email protected]>
 Steve Klabnik <[email protected]>
+Steven De Coeyer <[email protected]>
+Steven Fackler <[email protected]>
+Steven Stewart-Gallus <[email protected]>
 Taras Shpot <[email protected]>
 Ted Horst <[email protected]>
 Thad Guidry <[email protected]>
+Thomas Daede <[email protected]>
 Tim Chevalier <[email protected]>
 Tim Taubert <[email protected]>
 Tom Lee <[email protected]>
+Tommy M. McGuire <[email protected]>
 Tomoki Aonuma <[email protected]>
 Tony Young <[email protected]>
 Trinick <[email protected]>
 Tycho Sci <[email protected]>
 Tyler Bindon <[email protected]>
+Uwe Dauernheim <[email protected]>
+Vadim Chugunov <[email protected]>
 Viktor Dahl <[email protected]>
 Vincent Belliard <[email protected]>
+Vivek Galatage <[email protected]>
 Wade Mealing <[email protected]>
 William Ting <[email protected]>
 Yasuhiro Fujii <[email protected]>
 Young-il Choi <[email protected]>
+Youngmin Yoo <[email protected]>
 Youngsoo Son <[email protected]>
 Zack Corr <[email protected]>
+zofrex <[email protected]>

RELEASES.txt

@@ -7,12 +7,14 @@ Version 0.7 (July 2013)
       * `use mod` is no longer valid.
       * `fail!` and `assert!` accept `~str`, `&'static str` or `fmt!`-style
         argument list.
-      * `Encodable`, `Decodable`, `TotalOrd`, `TotalEq`, `DeepClone` can all
-        be automatically derived with `#[deriving(...)]`.
+      * `Encodable`, `Decodable`, `Ord`, `TotalOrd`, `TotalEq`, `DeepClone`,
+        `Rand`, `Zero` and `ToStr` can all be automatically derived with
+        `#[deriving(...)]`.
       * The `Durable` trait is replaced with the `'static` bounds.
       * At long last, 'argument modes' no longer exist.
       * The `bytes!` macro returns a vector of bytes for string, u8, char,
         and unsuffixed integer literals.
+      * `#[static_assert]` makes compile-time assertions about static bools.
 
    * Semantic changes
       * The borrow checker has been rewritten with flow-sensitivity, fixing
@@ -34,7 +36,7 @@ Version 0.7 (July 2013)
       * The `#[mutable]` attribute makes a type that would otherwise be
         `Const`, note. TODO this may change to non_freeze before 0.7
       * Unbounded recursion will abort the process after reaching the limit
-        specified by the `RUST_MAX_STACK` environment variable.
+        specified by the `RUST_MAX_STACK` environment variable (default: 1GB).
       * The `vecs_implicitly_copyable` lint mode has been removed. Vectors
         are never implicitly copyable.
 
@@ -46,30 +48,36 @@ Version 0.7 (July 2013)
       * std: Prelude additions: `print`, `println`, `FromStr`, `ApproxEq`, `Equiv`,
         `Iterator`, `IteratorUtil`, many numeric traits, many tuple traits.
       * std: `iterator` module for external iterator objects.
+      * std: Many old internal vector and string iterators,
+        incl. `any`, `all`. removed.
       * std: new numeric traits: `Fractional`, `Real`, `RealExt`, `Integer`, `Ratio`,
         `Algebraic`, `Trigonometric`, `Exponential`, `Primitive`.
       * std: Tuple traits and accessors defined for up to 12-tuples, e.g.
         `(0, 1, 2).n2()` or `(0, 1, 2).n2_ref()`.
-      * std: many types implement `Clone` - tuples, @, @mut. TODO
+      * std: many types implement `Clone`.
       * std: `path` type renamed to `Path`.
-      * std: Many standalone functions removed in favor of methods in
-        `vec`, `str`. In the future methods will also work as functions.
+      * std: Many standalone functions removed in favor of methods and iterators
+        in `vec`, `str`. In the future methods will also work as functions.
       * std: `reinterpret_cast` removed. Used `transmute`.
       * std: ascii string handling in `std::ascii`.
       * std: `Rand` is implemented for ~/@.
       * std: `run` module for spawning processes overhauled.
       * std: Various atomic types added to `unstable::atomic`.
       * std: `LinearMap` and `LinearSet` renamed to `HashMap` and `HashSet`.
+      * std: Borrowed pointer functions moved from `ptr` to `borrow`.
       * std: Added `os::mkdir_recursive`.
       * std: Added `os::glob` function performs filesystems globs.
       * std: `FuzzyEq` renamed to `ApproxEq`.
       * std: `Map` now defines `pop` and `swap` methods.
+      * std: `Cell` constructors converted to static methods.
+      * extra: `rc` module adds the reference counted pointers, `Rc` and `RcMut`.
       * extra: `flate` module moved from `std` to `extra`.
-      * extra: `FileInput` implements `std::io::Reader`.
+      * extra: `fileinput` module for iterating over a series of files.
       * extra: `Complex` number type and `complex` module.
       * extra: `Rational` number type and `rational` module.
       * extra: `BigInt`, `BigUint` implement numeric and comparison traits.
       * extra: `term` uses terminfo now, is more correct.
+      * extra: `arc` functions converted to methods.
 
    * Tooling
       * `unused_unsafe` lint mode for detecting unnecessary `unsafe` blocks.

doc/README

@@ -1,10 +1,25 @@
-The markdown docs are only generated by make when node is installed (use
-`make doc`). If you don't have node installed you can generate them yourself.
-Unfortunately there's no real standard for markdown and all the tools work
-differently. pandoc is one that seems to work well.
+Pandoc, a universal document converter, is required to generate docs as HTML
+from Rust's source code. It's available for most platforms here:
+http://johnmacfarlane.net/pandoc/installing.html
 
-To generate an html version of a doc do something like:
-pandoc --from=markdown --to=html --number-sections -o build/doc/rust.html doc/rust.md && git web--browse build/doc/rust.html
+Node.js (http://nodejs.org/) is also required for generating HTML from
+the Markdown docs (reference manual, tutorials, etc.) distributed with
+this git repository.
+
+To generate all the docs, run `make docs` from the root of the repository.
+This will convert the distributed Markdown docs to HTML and generate HTML doc
+for the 'std' and 'extra' libraries.
+
+To generate HTML documentation from one source file/crate, do something like:
+
+  rustdoc --output-dir html-doc/ --output-format html ../src/libstd/path.rs
+
+(This, of course, requires that you've built/installed the `rustdoc` tool.)
+
+To generate an HTML version of a doc from Markdown, without having Node.js
+installed, do something like:
+
+  pandoc --from=markdown --to=html --number-sections -o rust.html rust.md
 
 The syntax for pandoc flavored markdown can be found at:
 http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown

doc/rust.md

@@ -1561,6 +1561,7 @@ Supported traits for `deriving` are:
 * `Clone` and `DeepClone`, to perform (deep) copies.
 * `IterBytes`, to iterate over the bytes in a data type.
 * `Rand`, to create a random instance of a data type.
+* `Zero`, to create an zero (or empty) instance of a data type.
 * `ToStr`, to convert to a string. For a type with this instance,
   `obj.to_str()` has the same output as `fmt!("%?", obj)`.
 

doc/tutorial-borrowed-ptr.md

@@ -234,7 +234,7 @@ would therefore be subject to garbage collection. A heap box that is
 unrooted is one such that no pointer values in the heap point to
 it. It would violate memory safety for the box that was originally
 assigned to `x` to be garbage-collected, since a non-heap
-pointer---`y`---still points into it.
+pointer *`y`* still points into it.
 
 > ***Note:*** Our current implementation implements the garbage collector
 > using reference counting and cycle detection.
@@ -475,7 +475,7 @@ but otherwise it requires that the data reside in immutable memory.
 
 # Returning borrowed pointers
 
-So far, all of the examples we've looked at use borrowed pointers in a
+So far, all of the examples we have looked at, use borrowed pointers in a
 “downward” direction. That is, a method or code block creates a
 borrowed pointer, then uses it within the same scope. It is also
 possible to return borrowed pointers as the result of a function, but
@@ -509,7 +509,7 @@ guaranteed to refer to a distinct lifetime from the lifetimes of all
 other parameters.
 
 Named lifetimes that appear in function signatures are conceptually
-the same as the other lifetimes we've seen before, but they are a bit
+the same as the other lifetimes we have seen before, but they are a bit
 abstract: they don’t refer to a specific expression within `get_x()`,
 but rather to some expression within the *caller of `get_x()`*.  The
 lifetime `r` is actually a kind of *lifetime parameter*: it is defined

doc/tutorial-tasks.md

@@ -481,7 +481,7 @@ an `Error` result.
 TODO: Need discussion of `future_result` in order to make failure
 modes useful.
 
-But not all failure is created equal. In some cases you might need to
+But not all failures are created equal. In some cases you might need to
 abort the entire program (perhaps you're writing an assert which, if
 it trips, indicates an unrecoverable logic error); in other cases you
 might want to contain the failure at a certain boundary (perhaps a

doc/tutorial.md

@@ -1084,8 +1084,8 @@ let managed_box  : @Point = @Point { x: 5.0, y: 1.0 };
 let owned_box    : ~Point = ~Point { x: 7.0, y: 9.0 };
 ~~~
 
-Suppose we wanted to write a procedure that computed the distance
-between any two points, no matter where they were stored. For example,
+Suppose we want to write a procedure that computes the distance
+between any two points, no matter where they are stored. For example,
 we might like to compute the distance between `on_the_stack` and
 `managed_box`, or between `managed_box` and `owned_box`. One option is
 to define a function that takes two arguments of type point—that is,
@@ -1230,7 +1230,7 @@ let area = rect.area();
 ~~~
 
 You can write an expression that dereferences any number of pointers
-automatically. For example, if you felt inclined, you could write
+automatically. For example, if you feel inclined, you could write
 something silly like
 
 ~~~
@@ -1808,7 +1808,7 @@ s.draw_borrowed();
 ~~~
 
 Implementations may also define standalone (sometimes called "static")
-methods. The absence of a `self` paramater distinguishes such methods.
+methods. The absence of a `self` parameter distinguishes such methods.
 These methods are the preferred way to define constructor functions.
 
 ~~~~ {.xfail-test}
@@ -2319,7 +2319,7 @@ enum ABC { A, B, C }
 
 The full list of derivable traits is `Eq`, `TotalEq`, `Ord`,
 `TotalOrd`, `Encodable` `Decodable`, `Clone`, `DeepClone`,
-`IterBytes`, `Rand` and `ToStr`.
+`IterBytes`, `Rand`, `Zero`, and `ToStr`.
 
 # Modules and crates
 
@@ -2522,7 +2522,7 @@ will not be compiled successfully.
 
 ## A minimal example
 
-Now for something that you can actually compile yourself. We have
+Now for something that you can actually compile yourself, we have
 these two files:
 
 ~~~~

src/librustc/rustc.rc

@@ -140,10 +140,10 @@ pub fn version(argv0: &str) {
 
 pub fn usage(argv0: &str) {
     let message = fmt!("Usage: %s [OPTIONS] INPUT", argv0);
-    io::println(fmt!("%s \
-                Additional help: \
-    -W help             Print 'lint' options and default settings \
-    -Z help             Print internal options for debugging rustc",
+    io::println(fmt!("%s\
+Additional help:
+    -W help             Print 'lint' options and default settings
+    -Z help             Print internal options for debugging rustc\n",
                      groups::usage(message, optgroups())));
 }