Merge pull request #7270 from thestinger/doc

accumulated doc pull requests from the queue

Author: thestinger

AUTHORS.txt

@@ -10,9 +10,11 @@ Aleksander Balicki <balicki.aleksander@gmail.com>
 Alex Crichton <alex@alexcrichton.com>
 Alex Rønne Petersen <alex@lycus.org>
 Alexander Stavonin <a.stavonin@gmail.com>
+Alexei Sholik <alcosholik@gmail.com>
 Andreas Gal <gal@mozilla.com>
 Andrew Dunham <andrew@du.nham.ca>
 Andrew Paseltiner <apaseltiner@gmail.com>
+Anthony Juckel <ajuckel@gmail.com>
 Arkaitz Jimenez <arkaitzj@gmail.com>
 Armin Ronacher <armin.ronacher@active-4.com>
 Ashok Gautham <ScriptDevil@gmail.com>
@@ -29,23 +31,32 @@ Benjamin Kircher <benjamin.kircher@gmail.com>
 Benjamin Peterson <benjamin@python.org>
 Bilal Husain <bilal@bilalhusain.com>
 Bill Fallon <bill.fallon@robos.li>
+Bill Myers <bill_myers@outlook.com>
+Bill Wendling <wendling@apple.com>
+Björn Steinbrink <bsteinbr@gmail.com>
 Brendan Eich <brendan@mozilla.org>
 Brendan Zabarauskas <bjzaba@yahoo.com.au>
 Brett Cannon <brett@python.org>
 Brian Anderson <banderson@mozilla.com>
 Brian J. Burg <burg@cs.washington.edu>
 Brian Leibig <brian.leibig@gmail.com>
+Bryan Dunsmore <dunsmoreb@gmail.com>
+Caitlin Potter <snowball@defpixel.com>
 Chris Double <chris.double@double.co.nz>
 Chris Peterson <cpeterson@mozilla.com>
 Chris Pressey <cpressey@gmail.com>
 Cody Schroeder <codys@cs.washington.edu>
+Corey Richardson <corey@octayn.net>
 Damian Gryski <damian@gryski.com>
 Damien Grassart <damien@grassart.com>
 Damien Schoof <damien.schoof@gmail.com>
 Daniel Brooks <db48x@db48x.net>
+Daniel Farina <daniel@fdr.io>
+Dan Luu <danluu@gmail.com>
 Daniel Luz <dev@mernen.com>
 Daniel Micay <danielmicay@gmail.com>
 Daniel Patterson <dbp@riseup.net>
+Daniel Ralston <Wubbulous@gmail.com>
 Daniel Ursache Dogariu <contact@danniel.net>
 Dave Herman <dherman@mozilla.com>
 David Forsythe <dforsythe@gmail.com>
@@ -62,17 +73,21 @@ Eric Holmes <eric@ejholmes.net>
 Erick Tryzelaar <erick.tryzelaar@gmail.com>
 Erik Rose <erik@mozilla.com>
 Evan McClanahan <evan@evanmcc.com>
+Fedor Indutny <fedor.indutny@gmail.com>
 Felix S. Klock II <pnkfelix@pnkfx.org>
 Francisco Souza <f@souza.cc>
 Franklin Chen <franklinchen@franklinchen.com>
+Gábor Horváth <xazax.hun@gmail.com>
 Gabriel <g2p.code@gmail.com>
 Gareth Daniel Smith <garethdanielsmith@gmail.com>
+gifnksm <makoto.nksm@gmail.com>
 Glenn Willen <gwillen@nerdnet.org>
 Gonçalo Cabrita <_@gmcabrita.com>
 Graham Fawcett <fawcett@uwindsor.ca>
 Grahame Bowland <grahame@angrygoats.net>
 Haitao Li <lihaitao@gmail.com>
 hansjorg <hansjorg@gmail.com>
+Herman J. Radtke III <hermanradtke@gmail.com>
 Huon Wilson <dbau.pp+github@gmail.com>
 Ian D. Bollinger <ian.bollinger@gmail.com>
 Ilyong Cho <ilyoan@gmail.com>
@@ -83,6 +98,7 @@ Jacob Harris Cryer Kragh <jhckragh@gmail.com>
 Jacob Parker <j3parker@csclub.uwaterloo.ca>
 Jakub Wieczorek <jakubw@jakubw.net>
 James Miller <bladeon@gmail.com>
+James Tranovich <james@openhorizonlabs.com>
 Jason Orendorff <jorendorff@mozilla.com>
 Jed Davis <jld@panix.com>
 Jeff Balogh <jbalogh@mozilla.com>
@@ -92,6 +108,7 @@ Jeffrey Yasskin <jyasskin@gmail.com>
 Jeong YunWon <jeong@youknowone.org>
 Jens Nockert <jens@nockert.se>
 Jesse Jones <jesse9jones@gmail.com>
+Jesse Luehrs <doy@tozt.net>
 Jesse Ruderman <jruderman@gmail.com>
 Jihyun Yu <jihyun@nclab.kaist.ac.kr>
 Jim Blandy <jimb@red-bean.com>
@@ -104,14 +121,18 @@ Jonathan Sternberg <jonathansternberg@gmail.com>
 Josh Matthews <josh@joshmatthews.net>
 Joshua Clark <joshua.clark@txstate.edu>
 Joshua Wise <joshua@joshuawise.com>
+Junyoung Cho <june0.cho@samsung.com>
 Jyun-Yan You <jyyou@cs.nctu.edu.tw>
 Kang Seonghoon <kang.seonghoon@mearie.org>
 Kelly Wilson <wilsonk@cpsc.ucalgary.ca>
 Kevin Atkinson <kevina@cs.utah.edu>
+Kevin Ballard <kevin@sb.org>
 Kevin Cantu <me@kevincantu.org>
+klutzy <klutzytheklutzy@gmail.com>
 Kyeongwoon Lee <kyeongwoon.lee@samsung.com>
 Laurent Bonnans <bonnans.l@gmail.com>
 Lawrence Velázquez <larryv@alum.mit.edu>
+Leah Hanson <astrieanna@gmail.com>
 Lennart Kudling <github@kudling.de>
 Lindsey Kuper <lindsey@composition.al>
 Luca Bruno <lucab@debian.org>
@@ -122,6 +143,7 @@ Margaret Meyerhofer <mmeyerho@andrew.cmu.edu>
 Marijn Haverbeke <marijnh@gmail.com>
 Mark Lacey <641@rudkx.com>
 Mark Vian <mrv.caseus@gmail.com>
+Marti Raudsepp <marti@juffo.org>
 Martin DeMello <martindemello@gmail.com>
 Marvin Löbel <loebel.marvin@gmail.com>
 Matt Brubeck <mbrubeck@limpet.net>
@@ -143,43 +165,64 @@ Patrick Walton <pwalton@mozilla.com>
 Patrik Kårlin <patrik.karlin@gmail.com>
 Paul Stansifer <paul.stansifer@gmail.com>
 Paul Woolcock <pwoolcoc+github@gmail.com>
+Pavel Panchekha <me@pavpanchekha.com>
 Peter Hull <peterhull90@gmail.com>
 Peter Williams <peter@newton.cx>
 Philipp Brüschweiler <blei42@gmail.com>
 Rafael Ávila de Espíndola <respindola@mozilla.com>
+Ralph Bodenner <rkbodenner+github@gmail.com>
 Ralph Giles <giles@thaumas.net>
+Ramkumar Ramachandra <artagnon@gmail.com>
 Reuben Morais <reuben.morais@gmail.com>
 Rick Waldron <waldron.rick@gmail.com>
 Rob Arnold <robarnold@cs.cmu.edu>
+Rob Hoelz <rob@hoelz.ro>
 Roland Tanglao <roland@rolandtanglao.com>
+Ron Dahlgren <ronald.dahlgren@gmail.com>
 Roy Frostig <rfrostig@mozilla.com>
 Ryan Scheel <ryan.havvy@gmail.com>
+Samuel Chase <samebchase@gmail.com>
+Sander Mathijs van Veen <smvv@kompiler.org>
+Sangeun Kim <sammy.kim@samsung.com>
+Saurabh Anand <saurabhanandiit@gmail.com>
+Sean Moon <ssamoon@ucla.edu>
 Sean Stangl <sstangl@mozilla.com>
 Sebastian N. Fernandez <cachobot@gmail.com>
 Seth Pink <sethpink@gmail.com>
 Seo Sanghyeon <sanxiyn@gmail.com>
 sevrak <sevrak@rediffmail.com>
+SiegeLord <slabode@aim.com>
 Simon Barber-Dueck <sbarberdueck@gmail.com>
 Simon Sapin <simon@exyr.org>
 startling <tdixon51793@gmail.com>
 Stefan Plantikow <stefan.plantikow@googlemail.com>
 Steve Klabnik <steve@steveklabnik.com>
+Steven De Coeyer <steven@banteng.be>
+Steven Fackler <sfackler@gmail.com>
+Steven Stewart-Gallus <sstewartgallus00@langara.bc.ca>
 Taras Shpot <mrshpot@gmail.com>
 Ted Horst <ted.horst@earthlink.net>
 Thad Guidry <thadguidry@gmail.com>
+Thomas Daede <daede003@umn.edu>
 Tim Chevalier <chevalier@alum.wellesley.edu>
 Tim Taubert <tim@timtaubert.de>
 Tom Lee <github@tomlee.co>
+Tommy M. McGuire <mcguire@crsr.net>
 Tomoki Aonuma <uasi@99cm.org>
 Tony Young <tony@rfw.name>
 Trinick <slicksilver555@mac.com>
 Tycho Sci <tychosci@gmail.com>
 Tyler Bindon <martica@martica.org>
+Uwe Dauernheim <uwe@dauernheim.net>
+Vadim Chugunov <vadimcn@gmail.com>
 Viktor Dahl <pazaconyoman@gmail.com>
 Vincent Belliard <vincent@famillebelliard.fr>
+Vivek Galatage <vivekgalatage@gmail.com>
 Wade Mealing <wmealing@gmail.com>
 William Ting <william.h.ting@gmail.com>
 Yasuhiro Fujii <y-fujii@mimosa-pudica.net>
 Young-il Choi <duddlf.choi@samsung.com>
+Youngmin Yoo <youngmin.yoo@samsung.com>
 Youngsoo Son <ysson83@gmail.com>
 Zack Corr <zack@z0w0.me>
+zofrex <zofrex@gmail.com>

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())));
 }