Rollup merge of rust-lang#25290 - bluss:docfixes, r=steveklabnik

Several Minor API / Reference Documentation Fixes

- Fix a few small errors in the reference.
- Fix paper cuts in the API docs.

Fixes rust-lang#24882
Fixes rust-lang#25233
Fixes rust-lang#25250

Author: Manishearth

src/doc/reference.md

@@ -653,9 +653,10 @@ There are several kinds of item:
 * [`use` declarations](#use-declarations)
 * [modules](#modules)
 * [functions](#functions)
-* [type definitions](#type-definitions)
+* [type aliases](#type-aliases)
 * [structures](#structures)
 * [enumerations](#enumerations)
+* [constant items](#constant-items)
 * [static items](#static-items)
 * [traits](#traits)
 * [implementations](#implementations)
@@ -672,16 +673,16 @@ which sub-item declarations may appear.
 
 ### Type Parameters
 
-All items except modules may be *parameterized* by type. Type parameters are
-given as a comma-separated list of identifiers enclosed in angle brackets
-(`<...>`), after the name of the item and before its definition. The type
-parameters of an item are considered "part of the name", not part of the type
-of the item. A referencing [path](#paths) must (in principle) provide type
-arguments as a list of comma-separated types enclosed within angle brackets, in
-order to refer to the type-parameterized item. In practice, the type-inference
-system can usually infer such argument types from context. There are no
-general type-parametric types, only type-parametric items. That is, Rust has
-no notion of type abstraction: there are no first-class "forall" types.
+All items except modules, constants and statics may be *parameterized* by type.
+Type parameters are given as a comma-separated list of identifiers enclosed in
+angle brackets (`<...>`), after the name of the item and before its definition.
+The type parameters of an item are considered "part of the name", not part of
+the type of the item. A referencing [path](#paths) must (in principle) provide
+type arguments as a list of comma-separated types enclosed within angle
+brackets, in order to refer to the type-parameterized item. In practice, the
+type-inference system can usually infer such argument types from context. There
+are no general type-parametric types, only type-parametric items. That is, Rust
+has no notion of type abstraction: there are no first-class "forall" types.
 
 ### Modules
 
@@ -743,7 +744,7 @@ mod thread {
 }
 ```
 
-##### Extern crate declarations
+#### Extern crate declarations
 
 An _`extern crate` declaration_ specifies a dependency on an external crate.
 The external crate is then bound into the declaring scope as the `ident`
@@ -767,7 +768,7 @@ extern crate std; // equivalent to: extern crate std as std;
 extern crate std as ruststd; // linking to 'std' under another name
 ```
 
-##### Use declarations
+#### Use declarations
 
 A _use declaration_ creates one or more local name bindings synonymous with
 some other [path](#paths). Usually a `use` declaration is used to shorten the

src/libcollections/slice.rs

@@ -1002,7 +1002,7 @@ pub trait SliceConcatExt<T: ?Sized> {
     /// The resulting type after concatenation
     type Output;
 
-    /// Flattens a slice of `T` into a single value `U`.
+    /// Flattens a slice of `T` into a single value `Self::Output`.
     ///
     /// # Examples
     ///
@@ -1012,7 +1012,8 @@ pub trait SliceConcatExt<T: ?Sized> {
     #[stable(feature = "rust1", since = "1.0.0")]
     fn concat(&self) -> Self::Output;
 
-    /// Flattens a slice of `T` into a single value `U`, placing a given separator between each.
+    /// Flattens a slice of `T` into a single value `Self::Output`, placing a given separator
+    /// between each.
     ///
     /// # Examples
     ///

src/libcore/str/mod.rs

@@ -44,8 +44,11 @@ pub trait FromStr {
     #[stable(feature = "rust1", since = "1.0.0")]
     type Err;
 
-    /// Parses a string `s` to return an optional value of this type. If the
-    /// string is ill-formatted, the None is returned.
+    /// Parses a string `s` to return a value of this type.
+    ///
+    /// If parsing succeeds, return the value inside `Ok`, otherwise
+    /// when the string is ill-formatted return an error specific to the
+    /// inside `Err`. The error type is specific to implementation of the trait.
     #[stable(feature = "rust1", since = "1.0.0")]
     fn from_str(s: &str) -> Result<Self, Self::Err>;
 }

src/libstd/path.rs

@@ -1449,6 +1449,8 @@ impl Path {
 
     /// Determines whether `base` is a prefix of `self`.
     ///
+    /// Only considers whole path components to match.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1457,6 +1459,8 @@ impl Path {
     /// let path = Path::new("/etc/passwd");
     ///
     /// assert!(path.starts_with("/etc"));
+    ///
+    /// assert!(!path.starts_with("/e"));
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn starts_with<P: AsRef<Path>>(&self, base: P) -> bool {
@@ -1465,6 +1469,8 @@ impl Path {
 
     /// Determines whether `child` is a suffix of `self`.
     ///
+    /// Only considers whole path components to match.
+    ///
     /// # Examples
     ///
     /// ```

src/libstd/thread/local.rs

@@ -85,6 +85,8 @@ pub struct LocalKey<T> {
 }
 
 /// Declare a new thread local storage key of type `std::thread::LocalKey`.
+///
+/// See [LocalKey documentation](thread/struct.LocalKey.html) for more information.
 #[macro_export]
 #[stable(feature = "rust1", since = "1.0.0")]
 #[allow_internal_unstable]

src/libstd/thread/scoped_tls.rs

@@ -66,6 +66,8 @@ pub struct ScopedKey<T> { #[doc(hidden)] pub inner: __impl::KeyInner<T> }
 ///
 /// This macro declares a `static` item on which methods are used to get and
 /// set the value stored within.
+///
+/// See [ScopedKey documentation](thread/struct.ScopedKey.html) for more information.
 #[macro_export]
 #[allow_internal_unstable]
 macro_rules! scoped_thread_local {