auto merge of #15321 : huonw/rust/nil-prim, r=alexcrichton

This adds a primitive page for () like http://doc.rust-lang.org/master/std/uint/primitive.uint.html .

I would prefer the modules to be `std::tuple::unit`, but rustdoc only searches at the top level (filed as #15320).

src/libcore/lib.rs

@@ -122,6 +122,10 @@ pub mod simd;
 pub mod slice;
 pub mod str;
 pub mod tuple;
+// FIXME #15320: primitive documentation needs top-level modules, this
+// should be `core::tuple::unit`.
+#[path = "tuple/unit.rs"]
+pub mod unit;
 pub mod fmt;
 
 #[doc(hidden)]

src/libcore/tuple/mod.rs

@@ -61,6 +61,8 @@
 
 #![doc(primitive = "tuple")]
 
+pub use unit;
+
 use clone::Clone;
 use cmp::*;
 use default::Default;

src/libcore/tuple/unit.rs

@@ -0,0 +1,44 @@
+// Copyright 2014 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+#![doc(primitive = "unit")]
+
+//! The `()` type, sometimes called "unit" or "nil".
+//!
+//! The `()` type has exactly one value `()`, and is used when there
+//! is no other meaningful value that could be returned. `()` is most
+//! commonly seen implicitly: functions without a `-> ...` implicitly
+//! have return type `()`, that is, these are equivalent:
+//!
+//! ```rust
+//! fn long() -> () {}
+//!
+//! fn short() {}
+//! ```
+//!
+//! The semicolon `;` can be used to discard the result of an
+//! expression at the end of a block, making the expression (and thus
+//! the block) evaluate to `()`. For example,
+//!
+//! ```rust
+//! fn returns_i64() -> i64 {
+//!     1i64
+//! }
+//! fn returns_unit() {
+//!     1i64;
+//! }
+//!
+//! let is_i64 = {
+//!     returns_i64()
+//! };
+//! let is_unit = {
+//!     returns_i64();
+//! };
+//! ```

src/librustdoc/clean/mod.rs

@@ -1079,7 +1079,7 @@ pub enum Primitive {
     F32, F64,
     Char,
     Bool,
-    Nil,
+    Unit,
     Str,
     Slice,
     PrimitiveTuple,
@@ -1110,7 +1110,7 @@ impl Primitive {
             "u32" => Some(U32),
             "u64" => Some(U64),
             "bool" => Some(Bool),
-            "nil" => Some(Nil),
+            "unit" => Some(Unit),
             "char" => Some(Char),
             "str" => Some(Str),
             "f32" => Some(F32),
@@ -1159,7 +1159,7 @@ impl Primitive {
             Str => "str",
             Bool => "bool",
             Char => "char",
-            Nil => "()",
+            Unit => "()",
             Slice => "slice",
             PrimitiveTuple => "tuple",
         }
@@ -1167,7 +1167,7 @@ impl Primitive {
 
     pub fn to_url_str(&self) -> &'static str {
         match *self {
-            Nil => "nil",
+            Unit => "unit",
             other => other.to_str(),
         }
     }
@@ -1184,7 +1184,7 @@ impl Clean<Type> for ast::Ty {
     fn clean(&self) -> Type {
         use syntax::ast::*;
         match self.node {
-            TyNil => Primitive(Nil),
+            TyNil => Primitive(Unit),
             TyPtr(ref m) => RawPointer(m.mutbl.clean(), box m.ty.clean()),
             TyRptr(ref l, ref m) =>
                 BorrowedRef {lifetime: l.clean(), mutability: m.mutbl.clean(),
@@ -1214,7 +1214,7 @@ impl Clean<Type> for ty::t {
     fn clean(&self) -> Type {
         match ty::get(*self).sty {
             ty::ty_bot => Bottom,
-            ty::ty_nil => Primitive(Nil),
+            ty::ty_nil => Primitive(Unit),
             ty::ty_bool => Primitive(Bool),
             ty::ty_char => Primitive(Char),
             ty::ty_int(ast::TyI) => Primitive(Int),

src/librustdoc/html/format.rs

@@ -362,7 +362,7 @@ impl fmt::Show for clean::Type {
                        },
                        args = decl.decl.inputs,
                        arrow = match decl.decl.output {
-                           clean::Primitive(clean::Nil) => "".to_string(),
+                           clean::Primitive(clean::Unit) => "".to_string(),
                            _ => format!(" -> {}", decl.decl.output),
                        },
                        bounds = {
@@ -411,7 +411,7 @@ impl fmt::Show for clean::Type {
                                m.collect::<Vec<String>>().connect(" + "))
                        },
                        arrow = match decl.decl.output {
-                           clean::Primitive(clean::Nil) => "".to_string(),
+                           clean::Primitive(clean::Unit) => "".to_string(),
                            _ => format!(" -&gt; {}", decl.decl.output)
                        })
             }
@@ -472,7 +472,7 @@ impl fmt::Show for clean::FnDecl {
         write!(f, "({args}){arrow}",
                args = self.inputs,
                arrow = match self.output {
-                   clean::Primitive(clean::Nil) => "".to_string(),
+                   clean::Primitive(clean::Unit) => "".to_string(),
                    _ => format!(" -&gt; {}", self.output),
                })
     }
@@ -505,7 +505,7 @@ impl<'a> fmt::Show for Method<'a> {
         write!(f, "({args}){arrow}",
                args = args,
                arrow = match d.output {
-                   clean::Primitive(clean::Nil) => "".to_string(),
+                   clean::Primitive(clean::Unit) => "".to_string(),
                    _ => format!(" -&gt; {}", d.output),
                })
     }

src/libstd/lib.rs

@@ -160,6 +160,9 @@ pub use core::ptr;
 pub use core::raw;
 pub use core::simd;
 pub use core::tuple;
+// FIXME #15320: primitive documentation needs top-level modules, this
+// should be `std::tuple::unit`.
+pub use core::unit;
 #[cfg(not(test))] pub use core::ty;
 pub use core::result;
 pub use core::option;