Improve io docs

RELEASES.txt

@@ -30,7 +30,7 @@ Version 0.6 (April 2013)
         `@mut T`, `core::mut` or `core::cell`
       * `extern mod { ... }` is no longer valid syntax for foreign
         function modules. Use extern blocks: `extern { ... }`
-      * Newtype enums removed. Used tuple-structs.
+      * Newtype enums removed. Use tuple-structs.
       * Trait implementations no longer support visibility modifiers
       * Pattern matching over vectors improved and expanded
       * `const` renamed to `static` to correspond to lifetime name,
@@ -40,6 +40,10 @@ Version 0.6 (April 2013)
         `#[deriving(Clone)]`
       * Casts to traits must use a pointer sigil, e.g. `@foo as @Bar`
         instead of `foo as Bar`.
+      * Fixed length vector types are now written as `[int, .. 3]`
+        instead of `[int * 3]`.
+      * Fixed length vector types can express the length as a constant
+        expression. (ex: `[int, .. GL_BUFFER_SIZE - 2]`)
 
    * Semantic changes
       * Types with owned pointers or custom destructors move by default,

doc/tutorial.md

@@ -1539,9 +1539,9 @@ for spawning [tasks][tasks].
 
 Rust closures have a convenient subtyping property: you can pass any kind of
 closure (as long as the arguments and return types match) to functions
-that expect a `fn()`. Thus, when writing a higher-order function that
+that expect a `&fn()`. Thus, when writing a higher-order function that
 only calls its function argument, and does nothing else with it, you
-should almost always declare the type of that argument as `fn()`. That way,
+should almost always declare the type of that argument as `&fn()`. That way,
 callers may pass any kind of closure.
 
 ~~~~
@@ -2554,26 +2554,65 @@ a hash representing the crate metadata.
 
 ## The core library
 
-The Rust [core] library is the language runtime and contains
-required memory management and task scheduling code as well as a
-number of modules necessary for effective usage of the primitive
-types. Methods on [vectors] and [strings], implementations of most
-comparison and math operators, and pervasive types like [`Option`]
-and [`Result`] live in core.
+The Rust core 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.
 
-All Rust programs link to the core library and import its contents,
-as if the following were written at the top of the crate.
+[`core`] 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, `core` 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`]).
 
-~~~ {.xfail-test}
-extern mod core;
-use core::*;
-~~~
+### Core injection and the Rust prelude
 
-[core]: core/index.html
-[vectors]: core/vec.html
+`core` is imported at the topmost level of every crate by default, as
+if the first line of each crate was
+
+    extern mod core;
+
+This means that the contents of core can be accessed from from any context
+with the `core::` path prefix, as in `use core::vec`, `use core::task::spawn`,
+etc.
+
+Additionally, `core` contains a `prelude` module that reexports many of the
+most common core modules, types and traits. The contents of the prelude are
+imported into every *module* by default.  Implicitly, all modules behave as if
+they contained the following prologue:
+
+    use core::prelude::*;
+
+[`core`]: core/index.html
+[`bool`]: core/bool.html
+[tuples]: core/tuple.html
+[characters]: core/char.html
 [strings]: core/str.html
-[`Option`]: core/option.html
-[`Result`]: core/result.html
+[vectors]: core/vec.html
+[managed boxes]: core/managed.html
+[owned boxes]: core/owned.html
+[pointers]: core/ptr.html
+[`option`]: core/option.html
+[`result`]: core/result.html
+[task]: core/task.html
+[communication]: core/comm.html
+[`os`]: core/os.html
+[`path`]: core/path.html
+[`io`]: core/io.html
+[containers]: core/container.html
+[`hashmap`]: core/hashmap.html
+[`kinds`]: core/kinds.html
+[`ops`]: core/ops.html
+[`cmp`]: core/cmp.html
+[`num`]: core/num.html
+[`to_str`]: core/to_str.html
+[`clone`]: core/clone.html
+[`libc`]: core/libc.html
 
 # What next?
 
@@ -2585,10 +2624,7 @@ tutorials on individual topics.
 * [Macros][macros]
 * [The foreign function interface][ffi]
 
-There is further documentation on the [wiki], including articles about
-[unit testing] in Rust, [documenting][rustdoc] and [packaging][cargo]
-Rust code, and a discussion of the [attributes] used to apply metadata
-to code.
+There is further documentation on the [wiki].
 
 [borrow]: tutorial-borrowed-ptr.html
 [tasks]: tutorial-tasks.html

mk/install.mk

@@ -51,19 +51,19 @@ $(foreach target,$(CFG_TARGET_TRIPLES), \
 define INSTALL_TARGET_N
 install-target-$(1)-host-$(2): $$(TSREQ$$(ISTAGE)_T_$(1)_H_$(2)) $$(SREQ$$(ISTAGE)_T_$(1)_H_$(2))
 	$$(Q)mkdir -p $$(PTL$(1)$(2))
-	$$(Q)$$(call INSTALL,$$(TL$(1)$(2)),$$(PTL$(1)$(2)),$$(CFG_RUNTIME_$(1)))
+	$$(Q)$$(call INSTALL_LIB,$$(TL$(1)$(2)),$$(PTL$(1)$(2)),$$(CFG_RUNTIME_$(1)))
 	$$(Q)$$(call INSTALL_LIB, \
 		$$(TL$(1)$(2)),$$(PTL$(1)$(2)),$$(CORELIB_GLOB_$(1)))
 	$$(Q)$$(call INSTALL_LIB, \
 		$$(TL$(1)$(2)),$$(PTL$(1)$(2)),$$(STDLIB_GLOB_$(1)))
-	$$(Q)$$(call INSTALL,$$(TL$(1)$(2)),$$(PTL$(1)$(2)),libmorestack.a)
+	$$(Q)$$(call INSTALL_LIB,$$(TL$(1)$(2)),$$(PTL$(1)$(2)),libmorestack.a)
 
 endef
 
 define INSTALL_HOST_N
 install-target-$(1)-host-$(2): $$(CSREQ$$(ISTAGE)_T_$(1)_H_$(2))
 	$$(Q)mkdir -p $$(PTL$(1)$(2))
-	$$(Q)$$(call INSTALL,$$(TL$(1)$(2)),$$(PTL$(1)$(2)),$$(CFG_RUNTIME_$(1)))
+	$$(Q)$$(call INSTALL_LIB,$$(TL$(1)$(2)),$$(PTL$(1)$(2)),$$(CFG_RUNTIME_$(1)))
 	$$(Q)$$(call INSTALL_LIB, \
 		$$(TL$(1)$(2)),$$(PTL$(1)$(2)),$$(CORELIB_GLOB_$(1)))
 	$$(Q)$$(call INSTALL_LIB, \
@@ -80,7 +80,7 @@ install-target-$(1)-host-$(2): $$(CSREQ$$(ISTAGE)_T_$(1)_H_$(2))
 		$$(TL$(1)$(2)),$$(PTL$(1)$(2)),$$(LIBRUSTI_GLOB_$(1)))
 	$$(Q)$$(call INSTALL_LIB, \
 		$$(TL$(1)$(2)),$$(PTL$(1)$(2)),$$(LIBRUST_GLOB_$(1)))
-	$$(Q)$$(call INSTALL,$$(TL$(1)$(2)),$$(PTL$(1)$(2)),libmorestack.a)
+	$$(Q)$$(call INSTALL_LIB,$$(TL$(1)$(2)),$$(PTL$(1)$(2)),libmorestack.a)
 
 endef
 

mk/platform.mk

@@ -61,8 +61,6 @@ ifdef CFG_VALGRIND
 endif
 
 ifneq ($(findstring linux,$(CFG_OSTYPE)),)
-  # -znoexecstack is here because librt is for some reason being created
-  # with executable stack and Fedora (or SELinux) doesn't like that (#798)
   ifdef CFG_PERF
     ifneq ($(CFG_PERF_WITH_LOGFD),)
         CFG_PERF_TOOL := $(CFG_PERF) stat -r 3 --log-fd 2
@@ -126,7 +124,7 @@ CFG_GCCISH_CXXFLAGS_x86_64-unknown-linux-gnu := -fno-rtti
 CFG_GCCISH_LINK_FLAGS_x86_64-unknown-linux-gnu := -shared -fPIC -ldl -lpthread -lrt -g -m64
 CFG_GCCISH_DEF_FLAG_x86_64-unknown-linux-gnu := -Wl,--export-dynamic,--dynamic-list=
 CFG_GCCISH_PRE_LIB_FLAGS_x86_64-unknown-linux-gnu := -Wl,-whole-archive
-CFG_GCCISH_POST_LIB_FLAGS_x86_64-unknown-linux-gnu := -Wl,-no-whole-archive -Wl,-znoexecstack
+CFG_GCCISH_POST_LIB_FLAGS_x86_64-unknown-linux-gnu := -Wl,-no-whole-archive
 CFG_DEF_SUFFIX_x86_64-unknown-linux-gnu := .linux.def
 CFG_INSTALL_NAME_x86_64-unknown-linux-gnu =
 CFG_LIBUV_LINK_FLAGS_x86_64-unknown-linux-gnu =
@@ -152,7 +150,7 @@ CFG_GCCISH_CXXFLAGS_i686-unknown-linux-gnu := -fno-rtti
 CFG_GCCISH_LINK_FLAGS_i686-unknown-linux-gnu := -shared -fPIC -ldl -lpthread -lrt -g -m32
 CFG_GCCISH_DEF_FLAG_i686-unknown-linux-gnu := -Wl,--export-dynamic,--dynamic-list=
 CFG_GCCISH_PRE_LIB_FLAGS_i686-unknown-linux-gnu := -Wl,-whole-archive
-CFG_GCCISH_POST_LIB_FLAGS_i686-unknown-linux-gnu := -Wl,-no-whole-archive -Wl,-znoexecstack
+CFG_GCCISH_POST_LIB_FLAGS_i686-unknown-linux-gnu := -Wl,-no-whole-archive
 CFG_DEF_SUFFIX_i686-unknown-linux-gnu := .linux.def
 CFG_INSTALL_NAME_i686-unknown-linux-gnu =
 CFG_LIBUV_LINK_FLAGS_i686-unknown-linux-gnu =
@@ -228,7 +226,7 @@ CFG_GCCISH_CXXFLAGS_arm-linux-androideabi := -fno-rtti
 CFG_GCCISH_LINK_FLAGS_arm-linux-androideabi := -shared -fPIC -ldl -g -lm -lsupc++ -lgnustl_shared
 CFG_GCCISH_DEF_FLAG_arm-linux-androideabi := -Wl,--export-dynamic,--dynamic-list=
 CFG_GCCISH_PRE_LIB_FLAGS_arm-linux-androideabi := -Wl,-whole-archive
-CFG_GCCISH_POST_LIB_FLAGS_arm-linux-androideabi := -Wl,-no-whole-archive -Wl,-znoexecstack
+CFG_GCCISH_POST_LIB_FLAGS_arm-linux-androideabi := -Wl,-no-whole-archive
 CFG_DEF_SUFFIX_arm-linux-androideabi := .android.def
 CFG_INSTALL_NAME_arm-linux-androideabi =
 CFG_LIBUV_LINK_FLAGS_arm-linux-androideabi =

src/etc/vim/syntax/rust.vim

@@ -10,17 +10,20 @@ elseif exists("b:current_syntax")
   finish
 endif
 
-syn match     rustAssert      "\<assert\(\w\)*"
-syn keyword   rustKeyword     as break
-syn keyword   rustKeyword     copy do drop else extern
+syn keyword   rustConditional match if else
+syn keyword   rustOperator    as
+
+syn keyword   rustKeyword     break copy do drop extern
 syn keyword   rustKeyword     for if impl let log
-syn keyword   rustKeyword     loop match mod once priv pub pure
-syn keyword   rustKeyword     ref return static
+syn keyword   rustKeyword     copy do drop extern
+syn keyword   rustKeyword     for impl let log
+syn keyword   rustKeyword     loop mod once priv pub
+syn keyword   rustKeyword     return
 syn keyword   rustKeyword     unsafe use while
 " FIXME: Scoped impl's name is also fallen in this category
 syn keyword   rustKeyword     mod trait struct enum type nextgroup=rustIdentifier skipwhite
 syn keyword   rustKeyword     fn nextgroup=rustFuncName skipwhite
-syn keyword   rustStorage     const mut
+syn keyword   rustStorage     const mut ref static
 
 syn match     rustIdentifier  contains=rustIdentifierPrime "\%([^[:cntrl:][:space:][:punct:][:digit:]]\|_\)\%([^[:cntrl:][:punct:][:space:]]\|_\)*" display contained
 syn match     rustFuncName    "\%([^[:cntrl:][:space:][:punct:][:digit:]]\|_\)\%([^[:cntrl:][:punct:][:space:]]\|_\)*" display contained
@@ -71,8 +74,8 @@ syn keyword   rustConstant    STDIN_FILENO STDOUT_FILENO STDERR_FILENO
 syn match     rustModPath     "\w\(\w\)*::[^<]"he=e-3,me=e-3
 syn match     rustModPathSep  "::"
 
-syn match     rustFuncCall    "\w\(\w\)*("he=e-1,me=e-1 contains=rustAssert
-syn match     rustFuncCall    "\w\(\w\)*::<"he=e-3,me=e-3 contains=rustAssert " foo::<T>();
+syn match     rustFuncCall    "\w\(\w\)*("he=e-1,me=e-1
+syn match     rustFuncCall    "\w\(\w\)*::<"he=e-3,me=e-3 " foo::<T>();
 
 syn match     rustMacro       '\w\(\w\)*!'
 syn match     rustMacro       '#\w\(\w\)*'
@@ -110,8 +113,7 @@ syn match   rustCharacter   "'\([^'\\]\|\\\(['nrt\\\"]\|x\x\{2}\|u\x\{4}\|U\x\{8
 syn region    rustComment     start="/\*" end="\*/" contains=rustComment,rustTodo
 syn region    rustComment     start="//" skip="\\$" end="$" contains=rustTodo keepend
 
-
-syn keyword   rustTodo        TODO FIXME XXX NB unsafe
+syn keyword rustTodo contained TODO FIXME XXX NB
 
 hi def link rustHexNumber       rustNumber
 hi def link rustBinNumber       rustNumber
@@ -126,8 +128,9 @@ hi def link rustBoolean       Boolean
 hi def link rustConstant      Constant
 hi def link rustSelf          Constant
 hi def link rustFloat         Float
-hi def link rustAssert        Keyword
+hi def link rustOperator      Operator
 hi def link rustKeyword       Keyword
+hi def link rustConditional   Conditional
 hi def link rustIdentifier    Identifier
 hi def link rustModPath       Include
 hi def link rustFuncName      Function
@@ -140,7 +143,6 @@ hi def link rustStorage       StorageClass
 hi def link rustLifetime      Special
 
 " Other Suggestions:
-" hi rustAssert ctermfg=yellow
 " hi rustMacro ctermfg=magenta
 
 syn sync minlines=200

src/libcore/core.rc

@@ -39,7 +39,7 @@ etc.
 
 Additionally, `core` contains a `prelude` module that reexports many of the
 most common core modules, types and traits. The contents of the prelude are
-imported inte every *module* by default.  Implicitly, all modules behave as if
+imported into every *module* by default.  Implicitly, all modules behave as if
 they contained the following prologue:
 
     use core::prelude::*;
@@ -189,7 +189,6 @@ pub mod container;
 pub mod option;
 pub mod result;
 pub mod either;
-pub mod dlist;
 pub mod hashmap;
 pub mod cell;
 pub mod trie;

src/libcore/io.rs

@@ -49,29 +49,89 @@ pub mod rustrt {
 
 // FIXME (#2004): This is all buffered. We might need an unbuffered variant
 // as well
+/**
+* The SeekStyle enum describes the relationship between the position
+* we'd like to seek to from our current position. It's used as an argument
+* to the `seek` method defined on the `Reader` trait.
+*
+* There are three seek styles:
+* 
+* 1. `SeekSet` means that the new position should become our position.
+* 2. `SeekCur` means that we should seek from the current position.
+* 3. `SeekEnd` means that we should seek from the end.
+*
+* # Examples
+* 
+* None right now. 
+*/
 pub enum SeekStyle { SeekSet, SeekEnd, SeekCur, }
 
 
-/// The raw underlying reader trait. All readers must implement this.
+/**
+* The core Reader trait. All readers must implement this trait.
+*
+* # Examples
+* 
+* None right now. 
+*/
 pub trait Reader {
     // FIXME (#2004): Seekable really should be orthogonal.
 
-    /// Read up to len bytes (or EOF) and put them into bytes (which
-    /// must be at least len bytes long). Return number of bytes read.
     // FIXME (#2982): This should probably return an error.
+    /**
+    * Reads bytes and puts them into `bytes`. Returns the number of
+    * bytes read.
+    *
+    * The number of bytes to be read is `len` or the end of the file, 
+    * whichever comes first.
+    *
+    * The buffer must be at least `len` bytes long.
+    *
+    * # Examples
+    * 
+    * None right now. 
+    */
     fn read(&self, bytes: &mut [u8], len: uint) -> uint;
 
-    /// Read a single byte, returning a negative value for EOF or read error.
+    /**
+    * Reads a single byte.
+    *
+    * In the case of an EOF or an error, returns a negative value.
+    *
+    * # Examples
+    * 
+    * None right now. 
+    */
     fn read_byte(&self) -> int;
 
-    /// Return whether the stream is currently at EOF position.
+    /**
+    * Returns a boolean value: are we currently at EOF?
+    *
+    * # Examples
+    * 
+    * None right now. 
+    */
     fn eof(&self) -> bool;
 
-    /// Move the current position within the stream. The second parameter
-    /// determines the position that the first parameter is relative to.
+    /**
+    * Seek to a given `position` in the stream.
+    * 
+    * Takes an optional SeekStyle, which affects how we seek from the
+    * position. See `SeekStyle` docs for more details.
+    *
+    * # Examples
+    * 
+    * None right now. 
+    */
     fn seek(&self, position: int, style: SeekStyle);
 
-    /// Return the current position within the stream.
+    /**
+    * Returns the current position within the stream.
+    *
+    * # Examples
+    * 
+    * None right now. 
+    */
     fn tell(&self) -> uint;
 }
 

src/libcore/libc.rs

@@ -9,7 +9,19 @@
 // except according to those terms.
 
 /*!
-* Bindings for libc.
+* Bindings for the C standard library and other platform libraries
+*
+* This module contains bindings to the C standard library,
+* organized into modules by their defining standard.
+* Additionally, it contains some assorted platform-specific definitions.
+* For convenience, most functions and types are reexported from `core::libc`,
+* so `pub use core::libc::*` will import the available
+* C bindings as appropriate for the target platform. The exact
+* set of functions available are platform specific.
+*
+* *Note* Rustdoc does not indicate reexports currently. Also, because these
+* definitions are platform-specific, some may not
+* appear in the generated documentation.
 *
 * We consider the following specs reasonably normative with respect
 * to interoperating with the C standard library (libc/msvcrt):