Skip to content

Commit 8a45818

Browse files
borsbors
committed
auto merge of #17339 : treeman/rust/doc-things, r=alexcrichton
Also some cleanup to conform to documentation style.
2 parents eeda1b8 + a0d502b commit 8a45818

File tree

10 files changed

+636
-248
lines changed

10 files changed

+636
-248
lines changed

‎src/libcore/fmt/num.rs

+2-2
Original file line numberDiff line numberDiff line change
@@ -138,10 +138,10 @@ pub struct RadixFmt<T, R>(T, R);
138138
///
139139
/// # Example
140140
///
141-
/// ~~~
141+
/// ```
142142
/// use std::fmt::radix;
143143
/// assert_eq!(format!("{}", radix(55i, 36)), "1j".to_string());
144-
/// ~~~
144+
/// ```
145145
pub fn radix<T>(x: T, base: u8) -> RadixFmt<T, Radix> {
146146
RadixFmt(x, Radix::new(base))
147147
}

‎src/libcore/num/mod.rs

+4-4
Original file line numberDiff line numberDiff line change
@@ -61,10 +61,10 @@ pub trait Zero: Add<Self, Self> {
6161
///
6262
/// # Laws
6363
///
64-
/// ~~~text
64+
/// ```{.text}
6565
/// a + 0 = a ∀ a ∈ Self
6666
/// 0 + a = a ∀ a ∈ Self
67-
/// ~~~
67+
/// ```
6868
///
6969
/// # Purity
7070
///
@@ -114,10 +114,10 @@ pub trait One: Mul<Self, Self> {
114114
///
115115
/// # Laws
116116
///
117-
/// ~~~text
117+
/// ```{.text}
118118
/// a * 1 = a ∀ a ∈ Self
119119
/// 1 * a = a ∀ a ∈ Self
120-
/// ~~~
120+
/// ```
121121
///
122122
/// # Purity
123123
///

‎src/libcore/option.rs

+217-1
Original file line numberDiff line numberDiff line change
@@ -175,6 +175,16 @@ impl<T> Option<T> {
175175
/////////////////////////////////////////////////////////////////////////
176176

177177
/// Returns `true` if the option is a `Some` value
178+
///
179+
/// # Example
180+
///
181+
/// ```
182+
/// let x: Option<uint> = Some(2);
183+
/// assert_eq!(x.is_some(), true);
184+
///
185+
/// let x: Option<uint> = None;
186+
/// assert_eq!(x.is_some(), false);
187+
/// ```
178188
#[inline]
179189
#[stable]
180190
pub fn is_some(&self) -> bool {
@@ -185,6 +195,16 @@ impl<T> Option<T> {
185195
}
186196

187197
/// Returns `true` if the option is a `None` value
198+
///
199+
/// # Example
200+
///
201+
/// ```
202+
/// let x: Option<uint> = Some(2);
203+
/// assert_eq!(x.is_none(), false);
204+
///
205+
/// let x: Option<uint> = None;
206+
/// assert_eq!(x.is_none(), true);
207+
/// ```
188208
#[inline]
189209
#[stable]
190210
pub fn is_none(&self) -> bool {
@@ -218,13 +238,37 @@ impl<T> Option<T> {
218238
}
219239

220240
/// Convert from `Option<T>` to `Option<&mut T>`
241+
///
242+
/// # Example
243+
///
244+
/// ```
245+
/// let mut x = Some(2u);
246+
/// match x.as_mut() {
247+
/// Some(&ref mut v) => *v = 42,
248+
/// None => {},
249+
/// }
250+
/// assert_eq!(x, Some(42u));
251+
/// ```
221252
#[inline]
222253
#[unstable = "waiting for mut conventions"]
223254
pub fn as_mut<'r>(&'r mut self) -> Option<&'r mut T> {
224255
match *self { Some(ref mut x) => Some(x), None => None }
225256
}
226257

227258
/// Convert from `Option<T>` to `&mut [T]` (without copying)
259+
///
260+
/// # Example
261+
///
262+
/// ```
263+
/// let mut x = Some("Diamonds");
264+
/// {
265+
/// let v = x.as_mut_slice();
266+
/// assert!(v == ["Diamonds"]);
267+
/// v[0] = "Dirt";
268+
/// assert!(v == ["Dirt"]);
269+
/// }
270+
/// assert_eq!(x, Some("Dirt"));
271+
/// ```
228272
#[inline]
229273
#[unstable = "waiting for mut conventions"]
230274
pub fn as_mut_slice<'r>(&'r mut self) -> &'r mut [T] {
@@ -250,6 +294,18 @@ impl<T> Option<T> {
250294
///
251295
/// Fails if the value is a `None` with a custom failure message provided by
252296
/// `msg`.
297+
///
298+
/// # Example
299+
///
300+
/// ```
301+
/// let x = Some("value");
302+
/// assert_eq!(x.expect("the world is ending"), "value");
303+
/// ```
304+
///
305+
/// ```{.should_fail}
306+
/// let x: Option<&str> = None;
307+
/// x.expect("the world is ending"); // fails with `world is ending`
308+
/// ```
253309
#[inline]
254310
#[unstable = "waiting for conventions"]
255311
pub fn expect(self, msg: &str) -> T {
@@ -270,6 +326,18 @@ impl<T> Option<T> {
270326
/// In general, because this function may fail, its use is discouraged.
271327
/// Instead, prefer to use pattern matching and handle the `None`
272328
/// case explicitly.
329+
///
330+
/// # Example
331+
///
332+
/// ```
333+
/// let x = Some("air");
334+
/// assert_eq!(x.unwrap(), "air");
335+
/// ```
336+
///
337+
/// ```{.should_fail}
338+
/// let x: Option<&str> = None;
339+
/// assert_eq!(x.unwrap(), "air"); // fails
340+
/// ```
273341
#[inline]
274342
#[unstable = "waiting for conventions"]
275343
pub fn unwrap(self) -> T {
@@ -280,6 +348,13 @@ impl<T> Option<T> {
280348
}
281349

282350
/// Returns the contained value or a default.
351+
///
352+
/// # Example
353+
///
354+
/// ```
355+
/// assert_eq!(Some("car").unwrap_or("bike"), "car");
356+
/// assert_eq!(None.unwrap_or("bike"), "bike");
357+
/// ```
283358
#[inline]
284359
#[unstable = "waiting for conventions"]
285360
pub fn unwrap_or(self, def: T) -> T {
@@ -290,6 +365,14 @@ impl<T> Option<T> {
290365
}
291366

292367
/// Returns the contained value or computes it from a closure.
368+
///
369+
/// # Example
370+
///
371+
/// ```
372+
/// let k = 10u;
373+
/// assert_eq!(Some(4u).unwrap_or_else(|| 2 * k), 4u);
374+
/// assert_eq!(None.unwrap_or_else(|| 2 * k), 20u);
375+
/// ```
293376
#[inline]
294377
#[unstable = "waiting for conventions"]
295378
pub fn unwrap_or_else(self, f: || -> T) -> T {
@@ -321,13 +404,35 @@ impl<T> Option<T> {
321404
}
322405

323406
/// Applies a function to the contained value or returns a default.
407+
///
408+
/// # Example
409+
///
410+
/// ```
411+
/// let x = Some("foo");
412+
/// assert_eq!(x.map_or(42u, |v| v.len()), 3u);
413+
///
414+
/// let x: Option<&str> = None;
415+
/// assert_eq!(x.map_or(42u, |v| v.len()), 42u);
416+
/// ```
324417
#[inline]
325418
#[unstable = "waiting for unboxed closures"]
326419
pub fn map_or<U>(self, def: U, f: |T| -> U) -> U {
327420
match self { None => def, Some(t) => f(t) }
328421
}
329422

330423
/// Applies a function to the contained value or computes a default.
424+
///
425+
/// # Example
426+
///
427+
/// ```
428+
/// let k = 21u;
429+
///
430+
/// let x = Some("foo");
431+
/// assert_eq!(x.map_or_else(|| 2 * k, |v| v.len()), 3u);
432+
///
433+
/// let x: Option<&str> = None;
434+
/// assert_eq!(x.map_or_else(|| 2 * k, |v| v.len()), 42u);
435+
/// ```
331436
#[inline]
332437
#[unstable = "waiting for unboxed closures"]
333438
pub fn map_or_else<U>(self, def: || -> U, f: |T| -> U) -> U {
@@ -366,6 +471,16 @@ impl<T> Option<T> {
366471
/////////////////////////////////////////////////////////////////////////
367472

368473
/// Returns an iterator over the possibly contained value.
474+
///
475+
/// # Example
476+
///
477+
/// ```
478+
/// let x = Some(4u);
479+
/// assert_eq!(x.iter().next(), Some(&4));
480+
///
481+
/// let x: Option<uint> = None;
482+
/// assert_eq!(x.iter().next(), None);
483+
/// ```
369484
#[inline]
370485
#[unstable = "waiting for iterator conventions"]
371486
pub fn iter<'r>(&'r self) -> Item<&'r T> {
@@ -379,6 +494,20 @@ impl<T> Option<T> {
379494
}
380495

381496
/// Returns a mutable iterator over the possibly contained value.
497+
///
498+
/// # Example
499+
///
500+
/// ```
501+
/// let mut x = Some(4u);
502+
/// match x.iter_mut().next() {
503+
/// Some(&ref mut v) => *v = 42u,
504+
/// None => {},
505+
/// }
506+
/// assert_eq!(x, Some(42));
507+
///
508+
/// let mut x: Option<uint> = None;
509+
/// assert_eq!(x.iter_mut().next(), None);
510+
/// ```
382511
#[inline]
383512
#[unstable = "waiting for iterator conventions"]
384513
pub fn iter_mut<'r>(&'r mut self) -> Item<&'r mut T> {
@@ -392,6 +521,18 @@ impl<T> Option<T> {
392521
}
393522

394523
/// Returns a consuming iterator over the possibly contained value.
524+
///
525+
/// # Example
526+
///
527+
/// ```
528+
/// let x = Some("string");
529+
/// let v: Vec<&str> = x.into_iter().collect();
530+
/// assert_eq!(v, vec!["string"]);
531+
///
532+
/// let x = None;
533+
/// let v: Vec<&str> = x.into_iter().collect();
534+
/// assert_eq!(v, vec![]);
535+
/// ```
395536
#[inline]
396537
#[unstable = "waiting for iterator conventions"]
397538
pub fn into_iter(self) -> Item<T> {
@@ -403,6 +544,26 @@ impl<T> Option<T> {
403544
/////////////////////////////////////////////////////////////////////////
404545

405546
/// Returns `None` if the option is `None`, otherwise returns `optb`.
547+
///
548+
/// # Example
549+
///
550+
/// ```
551+
/// let x = Some(2u);
552+
/// let y: Option<&str> = None;
553+
/// assert_eq!(x.and(y), None);
554+
///
555+
/// let x: Option<uint> = None;
556+
/// let y = Some("foo");
557+
/// assert_eq!(x.and(y), None);
558+
///
559+
/// let x = Some(2u);
560+
/// let y = Some("foo");
561+
/// assert_eq!(x.and(y), Some("foo"));
562+
///
563+
/// let x: Option<uint> = None;
564+
/// let y: Option<&str> = None;
565+
/// assert_eq!(x.and(y), None);
566+
/// ```
406567
#[inline]
407568
#[stable]
408569
pub fn and<U>(self, optb: Option<U>) -> Option<U> {
@@ -414,6 +575,18 @@ impl<T> Option<T> {
414575

415576
/// Returns `None` if the option is `None`, otherwise calls `f` with the
416577
/// wrapped value and returns the result.
578+
///
579+
/// # Example
580+
///
581+
/// ```
582+
/// fn sq(x: uint) -> Option<uint> { Some(x * x) }
583+
/// fn nope(_: uint) -> Option<uint> { None }
584+
///
585+
/// assert_eq!(Some(2).and_then(sq).and_then(sq), Some(16));
586+
/// assert_eq!(Some(2).and_then(sq).and_then(nope), None);
587+
/// assert_eq!(Some(2).and_then(nope).and_then(sq), None);
588+
/// assert_eq!(None.and_then(sq).and_then(sq), None);
589+
/// ```
417590
#[inline]
418591
#[unstable = "waiting for unboxed closures"]
419592
pub fn and_then<U>(self, f: |T| -> Option<U>) -> Option<U> {
@@ -424,6 +597,26 @@ impl<T> Option<T> {
424597
}
425598

426599
/// Returns the option if it contains a value, otherwise returns `optb`.
600+
///
601+
/// # Example
602+
///
603+
/// ```
604+
/// let x = Some(2u);
605+
/// let y = None;
606+
/// assert_eq!(x.or(y), Some(2u));
607+
///
608+
/// let x = None;
609+
/// let y = Some(100u);
610+
/// assert_eq!(x.or(y), Some(100u));
611+
///
612+
/// let x = Some(2u);
613+
/// let y = Some(100u);
614+
/// assert_eq!(x.or(y), Some(2u));
615+
///
616+
/// let x: Option<uint> = None;
617+
/// let y = None;
618+
/// assert_eq!(x.or(y), None);
619+
/// ```
427620
#[inline]
428621
#[stable]
429622
pub fn or(self, optb: Option<T>) -> Option<T> {
@@ -435,6 +628,17 @@ impl<T> Option<T> {
435628

436629
/// Returns the option if it contains a value, otherwise calls `f` and
437630
/// returns the result.
631+
///
632+
/// # Example
633+
///
634+
/// ```
635+
/// fn nobody() -> Option<&'static str> { None }
636+
/// fn vikings() -> Option<&'static str> { Some("vikings") }
637+
///
638+
/// assert_eq!(Some("barbarians").or_else(vikings), Some("barbarians"));
639+
/// assert_eq!(None.or_else(vikings), Some("vikings"));
640+
/// assert_eq!(None.or_else(nobody), None);
641+
/// ```
438642
#[inline]
439643
#[unstable = "waiting for unboxed closures"]
440644
pub fn or_else(self, f: || -> Option<T>) -> Option<T> {
@@ -449,6 +653,18 @@ impl<T> Option<T> {
449653
/////////////////////////////////////////////////////////////////////////
450654

451655
/// Takes the value out of the option, leaving a `None` in its place.
656+
///
657+
/// # Example
658+
///
659+
/// ```
660+
/// let mut x = Some(2u);
661+
/// x.take();
662+
/// assert_eq!(x, None);
663+
///
664+
/// let mut x: Option<uint> = None;
665+
/// x.take();
666+
/// assert_eq!(x, None);
667+
/// ```
452668
#[inline]
453669
#[stable]
454670
pub fn take(&mut self) -> Option<T> {
@@ -613,7 +829,7 @@ impl<T> Default for Option<T> {
613829

614830
/// An `Option` iterator that yields either one or zero elements
615831
///
616-
/// The `Item` iterator is returned by the `iter`, `mut_iter` and `move_iter`
832+
/// The `Item` iterator is returned by the `iter`, `iter_mut` and `into_iter`
617833
/// methods on `Option`.
618834
#[deriving(Clone)]
619835
#[unstable = "waiting for iterator conventions"]

0 commit comments

Comments
 (0)