rustdoc: Submit examples to play.rust-lang.org

mk/docs.mk

@@ -43,7 +43,9 @@ L10N_LANGS := ja
 
 # The options are passed to the documentation generators.
 RUSTDOC_HTML_OPTS_NO_CSS = --markdown-before-content=doc/version_info.html \
-	--markdown-in-header=doc/favicon.inc --markdown-after-content=doc/footer.inc
+	--markdown-in-header=doc/favicon.inc \
+	--markdown-after-content=doc/footer.inc \
+	--markdown-playground-url='http://play.rust-lang.org/'
 
 RUSTDOC_HTML_OPTS = $(RUSTDOC_HTML_OPTS_NO_CSS) --markdown-css rust.css
 

src/doc/footer.inc

@@ -5,3 +5,5 @@ or the <a href="http://opensource.org/licenses/MIT">MIT license</a>, at your opt
 </p><p>
 This file may not be copied, modified, or distributed except according to those terms.
 </p></footer>
+<script type="text/javascript" src="jquery.js"></script>
+<script type="text/javascript" src="playpen.js"></script>

src/doc/guide-macros.md

@@ -11,7 +11,7 @@ which both pattern-match on their input and both return early in one case,
 doing nothing otherwise:
 
 ~~~~
-# enum T { SpecialA(uint), SpecialB(uint) };
+# enum T { SpecialA(uint), SpecialB(uint) }
 # fn f() -> uint {
 # let input_1 = SpecialA(0);
 # let input_2 = SpecialA(0);
@@ -37,7 +37,8 @@ lightweight custom syntax extensions, themselves defined using the
 the pattern in the above code:
 
 ~~~~
-# enum T { SpecialA(uint), SpecialB(uint) };
+# #![feature(macro_rules)]
+# enum T { SpecialA(uint), SpecialB(uint) }
 # fn f() -> uint {
 # let input_1 = SpecialA(0);
 # let input_2 = SpecialA(0);
@@ -55,6 +56,7 @@ early_return!(input_1 SpecialA);
 early_return!(input_2 SpecialB);
 # return 0;
 # }
+# fn main() {}
 ~~~~
 
 Macros are defined in pattern-matching style: in the above example, the text
@@ -155,7 +157,8 @@ separator token (a comma-separated list could be written `$(...),*`), and `+`
 instead of `*` to mean "at least one".
 
 ~~~~
-# enum T { SpecialA(uint),SpecialB(uint),SpecialC(uint),SpecialD(uint)};
+# #![feature(macro_rules)]
+# enum T { SpecialA(uint),SpecialB(uint),SpecialC(uint),SpecialD(uint)}
 # fn f() -> uint {
 # let input_1 = SpecialA(0);
 # let input_2 = SpecialA(0);
@@ -175,6 +178,7 @@ early_return!(input_1, [SpecialA|SpecialC|SpecialD]);
 early_return!(input_2, [SpecialB]);
 # return 0;
 # }
+# fn main() {}
 ~~~~
 
 ### Transcription
@@ -215,9 +219,10 @@ solves the problem.
 Now consider code like the following:
 
 ~~~~
-# enum T1 { Good1(T2, uint), Bad1};
+# #![feature(macro_rules)]
+# enum T1 { Good1(T2, uint), Bad1}
 # struct T2 { body: T3 }
-# enum T3 { Good2(uint), Bad2};
+# enum T3 { Good2(uint), Bad2}
 # fn f(x: T1) -> uint {
 match x {
     Good1(g1, val) => {
@@ -232,6 +237,7 @@ match x {
     _ => return 0 // default value
 }
 # }
+# fn main() {}
 ~~~~
 
 All the complicated stuff is deeply indented, and the error-handling code is
@@ -240,6 +246,7 @@ a match, but with a syntax that suits the problem better. The following macro
 can solve the problem:
 
 ~~~~
+# #![feature(macro_rules)]
 macro_rules! biased_match (
     // special case: `let (x) = ...` is illegal, so use `let x = ...` instead
     ( ($e:expr) ~ ($p:pat) else $err:stmt ;
@@ -261,9 +268,9 @@ macro_rules! biased_match (
     )
 )
 
-# enum T1 { Good1(T2, uint), Bad1};
+# enum T1 { Good1(T2, uint), Bad1}
 # struct T2 { body: T3 }
-# enum T3 { Good2(uint), Bad2};
+# enum T3 { Good2(uint), Bad2}
 # fn f(x: T1) -> uint {
 biased_match!((x)       ~ (Good1(g1, val)) else { return 0 };
               binds g1, val )
@@ -273,13 +280,16 @@ biased_match!((g1.body) ~ (Good2(result) )
 // complicated stuff goes here
 return result + val;
 # }
+# fn main() {}
 ~~~~
 
 This solves the indentation problem. But if we have a lot of chained matches
 like this, we might prefer to write a single macro invocation. The input
 pattern we want is clear:
 
 ~~~~
+# #![feature(macro_rules)]
+# fn main() {}
 # macro_rules! b(
     ( $( ($e:expr) ~ ($p:pat) else $err:stmt ; )*
       binds $( $bind_res:ident ),*
@@ -301,14 +311,18 @@ process the semicolon-terminated lines, one-by-one. So, we want the following
 input patterns:
 
 ~~~~
+# #![feature(macro_rules)]
 # macro_rules! b(
     ( binds $( $bind_res:ident ),* )
 # => (0))
+# fn main() {}
 ~~~~
 
 ...and:
 
 ~~~~
+# #![feature(macro_rules)]
+# fn main() {}
 # macro_rules! b(
     (    ($e     :expr) ~ ($p     :pat) else $err     :stmt ;
       $( ($e_rest:expr) ~ ($p_rest:pat) else $err_rest:stmt ; )*
@@ -322,6 +336,8 @@ The resulting macro looks like this. Note that the separation into
 piece of syntax (the `let`) which we only want to transcribe once.
 
 ~~~~
+# #![feature(macro_rules)]
+# fn main() {
 
 macro_rules! biased_match_rec (
     // Handle the first layer
@@ -365,9 +381,9 @@ macro_rules! biased_match (
 )
 
 
-# enum T1 { Good1(T2, uint), Bad1};
+# enum T1 { Good1(T2, uint), Bad1}
 # struct T2 { body: T3 }
-# enum T3 { Good2(uint), Bad2};
+# enum T3 { Good2(uint), Bad2}
 # fn f(x: T1) -> uint {
 biased_match!(
     (x)       ~ (Good1(g1, val)) else { return 0 };
@@ -376,6 +392,7 @@ biased_match!(
 // complicated stuff goes here
 return result + val;
 # }
+# }
 ~~~~
 
 This technique applies to many cases where transcribing a result all at once is not possible.

src/doc/guide-unsafe.md

@@ -523,6 +523,7 @@ vectors provided from C, using idiomatic Rust practices.
 
 ```
 #![no_std]
+#![feature(globs)]
 
 # extern crate libc;
 extern crate core;

src/doc/rust.css

@@ -313,6 +313,19 @@ table th {
     padding: 5px;
 }
 
+/* Code snippets */
+
+.rusttest { display: none; }
+pre.rust { position: relative; }
+pre.rust a { transform: scaleX(-1); }
+.test-arrow {
+    display: inline-block;
+    position: absolute;
+    top: 0;
+    right: 10px;
+    font-size: 150%;
+}
+
 @media (min-width: 1170px) {
     pre {
         font-size: 15px;

src/doc/rust.md

@@ -1260,13 +1260,16 @@ a = Cat;
 Enumeration constructors can have either named or unnamed fields:
 
 ~~~~
+# #![feature(struct_variant)]
+# fn main() {
 enum Animal {
     Dog (String, f64),
     Cat { name: String, weight: f64 }
 }
 
 let mut a: Animal = Dog("Cocoa".to_string(), 37.2);
 a = Cat { name: "Spotty".to_string(), weight: 2.7 };
+# }
 ~~~~
 
 In this example, `Cat` is a _struct-like enum variant_,

src/doc/tutorial.md

@@ -774,6 +774,7 @@ fn point_from_direction(dir: Direction) -> Point {
 Enum variants may also be structs. For example:
 
 ~~~~
+# #![feature(struct_variant)]
 use std::f64;
 # struct Point { x: f64, y: f64 }
 # fn square(x: f64) -> f64 { x * x }
@@ -789,6 +790,7 @@ fn area(sh: Shape) -> f64 {
         }
     }
 }
+# fn main() {}
 ~~~~
 
 > *Note:* This feature of the compiler is currently gated behind the
@@ -3046,6 +3048,7 @@ use farm::{chicken, cow};
 2. Import everything in a module with a wildcard:
 
 ~~~
+# #![feature(globs)]
 use farm::*;
 # mod farm {
 #     pub fn cow() { println!("Bat-chicken? What a stupid name!") }

src/libcollections/lib.rs

@@ -17,7 +17,8 @@
 #![license = "MIT/ASL2"]
 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
        html_favicon_url = "http://www.rust-lang.org/favicon.ico",
-       html_root_url = "http://doc.rust-lang.org/")]
+       html_root_url = "http://doc.rust-lang.org/",
+       html_playground_url = "http://play.rust-lang.org/")]
 
 #![feature(macro_rules, managed_boxes, default_type_params, phase, globs)]
 #![no_std]

src/libcore/lib.rs

@@ -50,7 +50,8 @@
 #![crate_type = "rlib"]
 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
        html_favicon_url = "http://www.rust-lang.org/favicon.ico",
-       html_root_url = "http://doc.rust-lang.org/")]
+       html_root_url = "http://doc.rust-lang.org/",
+       html_playground_url = "http://play.rust-lang.org/")]
 
 #![no_std]
 #![feature(globs, macro_rules, managed_boxes, phase, simd)]

src/libgetopts/lib.rs

@@ -84,7 +84,8 @@
 #![license = "MIT/ASL2"]
 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
        html_favicon_url = "http://www.rust-lang.org/favicon.ico",
-       html_root_url = "http://doc.rust-lang.org/")]
+       html_root_url = "http://doc.rust-lang.org/",
+       html_playground_url = "http://play.rust-lang.org/")]
 #![feature(globs, phase)]
 #![deny(missing_doc)]
 #![deny(deprecated_owned_vector)]

src/libglob/lib.rs

@@ -29,8 +29,8 @@
 #![license = "MIT/ASL2"]
 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
        html_favicon_url = "http://www.rust-lang.org/favicon.ico",
-       html_root_url = "http://doc.rust-lang.org/")]
-
+       html_root_url = "http://doc.rust-lang.org/",
+       html_playground_url = "http://play.rust-lang.org/")]
 #![deny(deprecated_owned_vector)]
 
 use std::cell::Cell;

src/libgreen/lib.rs

@@ -203,7 +203,8 @@
 #![crate_type = "dylib"]
 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
        html_favicon_url = "http://www.rust-lang.org/favicon.ico",
-       html_root_url = "http://doc.rust-lang.org/")]
+       html_root_url = "http://doc.rust-lang.org/",
+       html_playground_url = "http://play.rust-lang.org/")]
 
 // NB this does *not* include globs, please keep it that way.
 #![feature(macro_rules, phase)]

src/liblog/lib.rs

@@ -111,7 +111,8 @@ if logging is disabled, none of the components of the log will be executed.
 #![crate_type = "dylib"]
 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
        html_favicon_url = "http://www.rust-lang.org/favicon.ico",
-       html_root_url = "http://doc.rust-lang.org/")]
+       html_root_url = "http://doc.rust-lang.org/",
+       html_playground_url = "http://play.rust-lang.org/")]
 
 #![feature(macro_rules)]
 #![deny(missing_doc, deprecated_owned_vector)]

src/libnum/lib.rs

@@ -50,7 +50,8 @@
 #![license = "MIT/ASL2"]
 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
        html_favicon_url = "http://www.rust-lang.org/favicon.ico",
-       html_root_url = "http://doc.rust-lang.org/")]
+       html_root_url = "http://doc.rust-lang.org/",
+       html_playground_url = "http://play.rust-lang.org/")]
 
 #![deny(deprecated_owned_vector)]
 

src/librand/lib.rs

@@ -21,7 +21,8 @@
 #![crate_type = "rlib"]
 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk.png",
        html_favicon_url = "http://www.rust-lang.org/favicon.ico",
-       html_root_url = "http://doc.rust-lang.org/")]
+       html_root_url = "http://doc.rust-lang.org/",
+       html_playground_url = "http://play.rust-lang.org/")]
 
 #![feature(macro_rules, phase, globs)]
 #![no_std]

src/libregex/lib.rs

@@ -360,7 +360,8 @@
 #![license = "MIT/ASL2"]
 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
        html_favicon_url = "http://www.rust-lang.org/favicon.ico",
-       html_root_url = "http://doc.rust-lang.org/")]
+       html_root_url = "http://doc.rust-lang.org/",
+       html_playground_url = "http://play.rust-lang.org/")]
 
 #![feature(macro_rules, phase)]
 #![deny(missing_doc, deprecated_owned_vector)]

src/librustdoc/html/highlight.rs

@@ -25,7 +25,7 @@ use html::escape::Escape;
 use t = syntax::parse::token;
 
 /// Highlights some source code, returning the HTML output.
-pub fn highlight(src: &str, class: Option<&str>) -> String {
+pub fn highlight(src: &str, class: Option<&str>, id: Option<&str>) -> String {
     debug!("highlighting: ================\n{}\n==============", src);
     let sess = parse::new_parse_sess();
     let fm = parse::string_to_filemap(&sess,
@@ -36,6 +36,7 @@ pub fn highlight(src: &str, class: Option<&str>) -> String {
     doit(&sess,
          lexer::StringReader::new(&sess.span_diagnostic, fm),
          class,
+         id,
          &mut out).unwrap();
     str::from_utf8_lossy(out.unwrap().as_slice()).to_string()
 }
@@ -47,11 +48,17 @@ pub fn highlight(src: &str, class: Option<&str>) -> String {
 /// it's used. All source code emission is done as slices from the source map,
 /// not from the tokens themselves, in order to stay true to the original
 /// source.
-fn doit(sess: &parse::ParseSess, mut lexer: lexer::StringReader, class: Option<&str>,
+fn doit(sess: &parse::ParseSess, mut lexer: lexer::StringReader,
+        class: Option<&str>, id: Option<&str>,
         out: &mut Writer) -> io::IoResult<()> {
     use syntax::parse::lexer::Reader;
 
-    try!(write!(out, "<pre class='rust {}'>\n", class.unwrap_or("")));
+    try!(write!(out, "<pre "));
+    match id {
+        Some(id) => try!(write!(out, "id='{}' ", id)),
+        None => {}
+    }
+    try!(write!(out, "class='rust {}'>\n", class.unwrap_or("")));
     let mut last = BytePos(0);
     let mut is_attribute = false;
     let mut is_macro = false;