Add “Examples” section header in f32/f64 doc comments.

This is recommend by [RFC 0505] and as far as I know, the only primitive
types without this heading.

[RFC 0505]: https://github.com/rust-lang/rfcs/blob/c892139be692586e0846fbf934be6fceec17f329/text/0505-api-comment-conventions.md#using-markdown

diff --git a/src/libstd/f32.rs b/src/libstd/f32.rs
index f849db4ec6027ea8ee962fc58b475c74f4a2ac10..7314d32b0206afaf21f55ca3a4cc925a0bf6bd2a 100644 (file)
--- a/src/libstd/f32.rs
+++ b/src/libstd/f32.rs
@@ -49,6 +49,8 @@ impl f32 {
 
     /// Returns the largest integer less than or equal to a number.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let f = 3.99_f32;
     /// let g = 3.0_f32;
@@ -80,6 +82,8 @@ pub fn floor(self) -> f32 {
 
     /// Returns the smallest integer greater than or equal to a number.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let f = 3.01_f32;
     /// let g = 4.0_f32;
@@ -100,6 +104,8 @@ pub fn ceil(self) -> f32 {
     /// Returns the nearest integer to a number. Round half-way cases away from
     /// `0.0`.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let f = 3.3_f32;
     /// let g = -3.3_f32;
@@ -115,6 +121,8 @@ pub fn round(self) -> f32 {
 
     /// Returns the integer part of a number.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let f = 3.3_f32;
     /// let g = -3.7_f32;
@@ -130,6 +138,8 @@ pub fn trunc(self) -> f32 {
 
     /// Returns the fractional part of a number.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -148,6 +158,8 @@ pub fn fract(self) -> f32 { self - self.trunc() }
     /// Computes the absolute value of `self`. Returns `NAN` if the
     /// number is `NAN`.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -174,6 +186,8 @@ pub fn abs(self) -> f32 {
     /// - `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY`
     /// - `NAN` if the number is `NAN`
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -200,6 +214,8 @@ pub fn signum(self) -> f32 {
     /// Using `mul_add` can be more performant than an unfused multiply-add if
     /// the target architecture has a dedicated `fma` CPU instruction.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -225,6 +241,8 @@ pub fn mul_add(self, a: f32, b: f32) -> f32 {
     /// In other words, the result is `self / rhs` rounded to the integer `n`
     /// such that `self >= n * rhs`.
     ///
+    /// # Examples
+    ///
     /// ```
     /// #![feature(euclidean_division)]
     /// let a: f32 = 7.0;
@@ -248,6 +266,8 @@ pub fn div_euc(self, rhs: f32) -> f32 {
     ///
     /// In particular, the result `n` satisfies `0 <= n < rhs.abs()`.
     ///
+    /// # Examples
+    ///
     /// ```
     /// #![feature(euclidean_division)]
     /// let a: f32 = 7.0;
@@ -273,6 +293,8 @@ pub fn mod_euc(self, rhs: f32) -> f32 {
     ///
     /// Using this function is generally faster than using `powf`
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -289,6 +311,8 @@ pub fn powi(self, n: i32) -> f32 {
 
     /// Raises a number to a floating point power.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -311,6 +335,8 @@ pub fn powf(self, n: f32) -> f32 {
     ///
     /// Returns NaN if `self` is a negative number.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -334,6 +360,8 @@ pub fn sqrt(self) -> f32 {
 
     /// Returns `e^(self)`, (the exponential function).
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -358,6 +386,8 @@ pub fn exp(self) -> f32 {
 
     /// Returns `2^(self)`.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -376,6 +406,8 @@ pub fn exp2(self) -> f32 {
 
     /// Returns the natural logarithm of the number.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -404,6 +436,8 @@ pub fn ln(self) -> f32 {
     /// `self.log2()` can produce more accurate results for base 2, and
     /// `self.log10()` can produce more accurate results for base 10.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -420,6 +454,8 @@ pub fn log(self, base: f32) -> f32 { self.ln() / base.ln() }
 
     /// Returns the base 2 logarithm of the number.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -441,6 +477,8 @@ pub fn log2(self) -> f32 {
 
     /// Returns the base 10 logarithm of the number.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -466,6 +504,8 @@ pub fn log10(self) -> f32 {
     /// * If `self <= other`: `0:0`
     /// * Else: `self - other`
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -493,6 +533,8 @@ pub fn abs_sub(self, other: f32) -> f32 {
 
     /// Takes the cubic root of a number.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -512,6 +554,8 @@ pub fn cbrt(self) -> f32 {
     /// Calculates the length of the hypotenuse of a right-angle triangle given
     /// legs of length `x` and `y`.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -531,6 +575,8 @@ pub fn hypot(self, other: f32) -> f32 {
 
     /// Computes the sine of a number (in radians).
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -552,6 +598,8 @@ pub fn sin(self) -> f32 {
 
     /// Computes the cosine of a number (in radians).
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -573,6 +621,8 @@ pub fn cos(self) -> f32 {
 
     /// Computes the tangent of a number (in radians).
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -591,6 +641,8 @@ pub fn tan(self) -> f32 {
     /// the range [-pi/2, pi/2] or NaN if the number is outside the range
     /// [-1, 1].
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -611,6 +663,8 @@ pub fn asin(self) -> f32 {
     /// the range [0, pi] or NaN if the number is outside the range
     /// [-1, 1].
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -630,6 +684,8 @@ pub fn acos(self) -> f32 {
     /// Computes the arctangent of a number. Return value is in radians in the
     /// range [-pi/2, pi/2];
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -653,6 +709,8 @@ pub fn atan(self) -> f32 {
     /// * `y >= 0`: `arctan(y/x) + pi` -> `(pi/2, pi]`
     /// * `y < 0`: `arctan(y/x) - pi` -> `(-pi, -pi/2)`
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -682,6 +740,8 @@ pub fn atan2(self, other: f32) -> f32 {
     /// Simultaneously computes the sine and cosine of the number, `x`. Returns
     /// `(sin(x), cos(x))`.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -703,6 +763,8 @@ pub fn sin_cos(self) -> (f32, f32) {
     /// Returns `e^(self) - 1` in a way that is accurate even if the
     /// number is close to zero.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -722,6 +784,8 @@ pub fn exp_m1(self) -> f32 {
     /// Returns `ln(1+n)` (natural logarithm) more accurately than if
     /// the operations were performed separately.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -740,6 +804,8 @@ pub fn ln_1p(self) -> f32 {
 
     /// Hyperbolic sine function.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -761,6 +827,8 @@ pub fn sinh(self) -> f32 {
 
     /// Hyperbolic cosine function.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -782,6 +850,8 @@ pub fn cosh(self) -> f32 {
 
     /// Hyperbolic tangent function.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -803,6 +873,8 @@ pub fn tanh(self) -> f32 {
 
     /// Inverse hyperbolic sine function.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -825,6 +897,8 @@ pub fn asinh(self) -> f32 {
 
     /// Inverse hyperbolic cosine function.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///
@@ -846,6 +920,8 @@ pub fn acosh(self) -> f32 {
 
     /// Inverse hyperbolic tangent function.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f32;
     ///

diff --git a/src/libstd/f64.rs b/src/libstd/f64.rs
index 40c3f4d0ef72623716a591a2d52559fa45644a28..75edba8979f9a1993515bf2c492381e61a5d13e5 100644 (file)
--- a/src/libstd/f64.rs
+++ b/src/libstd/f64.rs
@@ -49,6 +49,8 @@ impl f64 {
 
     /// Returns the largest integer less than or equal to a number.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let f = 3.99_f64;
     /// let g = 3.0_f64;
@@ -64,6 +66,8 @@ pub fn floor(self) -> f64 {
 
     /// Returns the smallest integer greater than or equal to a number.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let f = 3.01_f64;
     /// let g = 4.0_f64;
@@ -80,6 +84,8 @@ pub fn ceil(self) -> f64 {
     /// Returns the nearest integer to a number. Round half-way cases away from
     /// `0.0`.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let f = 3.3_f64;
     /// let g = -3.3_f64;
@@ -95,6 +101,8 @@ pub fn round(self) -> f64 {
 
     /// Returns the integer part of a number.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let f = 3.3_f64;
     /// let g = -3.7_f64;
@@ -110,6 +118,8 @@ pub fn trunc(self) -> f64 {
 
     /// Returns the fractional part of a number.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let x = 3.5_f64;
     /// let y = -3.5_f64;
@@ -126,6 +136,8 @@ pub fn fract(self) -> f64 { self - self.trunc() }
     /// Computes the absolute value of `self`. Returns `NAN` if the
     /// number is `NAN`.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f64;
     ///
@@ -152,6 +164,8 @@ pub fn abs(self) -> f64 {
     /// - `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY`
     /// - `NAN` if the number is `NAN`
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f64;
     ///
@@ -178,6 +192,8 @@ pub fn signum(self) -> f64 {
     /// Using `mul_add` can be more performant than an unfused multiply-add if
     /// the target architecture has a dedicated `fma` CPU instruction.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let m = 10.0_f64;
     /// let x = 4.0_f64;
@@ -201,6 +217,8 @@ pub fn mul_add(self, a: f64, b: f64) -> f64 {
     /// In other words, the result is `self / rhs` rounded to the integer `n`
     /// such that `self >= n * rhs`.
     ///
+    /// # Examples
+    ///
     /// ```
     /// #![feature(euclidean_division)]
     /// let a: f64 = 7.0;
@@ -224,6 +242,8 @@ pub fn div_euc(self, rhs: f64) -> f64 {
     ///
     /// In particular, the result `n` satisfies `0 <= n < rhs.abs()`.
     ///
+    /// # Examples
+    ///
     /// ```
     /// #![feature(euclidean_division)]
     /// let a: f64 = 7.0;
@@ -248,6 +268,8 @@ pub fn mod_euc(self, rhs: f64) -> f64 {
     ///
     /// Using this function is generally faster than using `powf`
     ///
+    /// # Examples
+    ///
     /// ```
     /// let x = 2.0_f64;
     /// let abs_difference = (x.powi(2) - x*x).abs();
@@ -262,6 +284,8 @@ pub fn powi(self, n: i32) -> f64 {
 
     /// Raises a number to a floating point power.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let x = 2.0_f64;
     /// let abs_difference = (x.powf(2.0) - x*x).abs();
@@ -278,6 +302,8 @@ pub fn powf(self, n: f64) -> f64 {
     ///
     /// Returns NaN if `self` is a negative number.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let positive = 4.0_f64;
     /// let negative = -4.0_f64;
@@ -299,6 +325,8 @@ pub fn sqrt(self) -> f64 {
 
     /// Returns `e^(self)`, (the exponential function).
     ///
+    /// # Examples
+    ///
     /// ```
     /// let one = 1.0_f64;
     /// // e^1
@@ -317,6 +345,8 @@ pub fn exp(self) -> f64 {
 
     /// Returns `2^(self)`.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let f = 2.0_f64;
     ///
@@ -333,6 +363,8 @@ pub fn exp2(self) -> f64 {
 
     /// Returns the natural logarithm of the number.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let one = 1.0_f64;
     /// // e^1
@@ -355,6 +387,8 @@ pub fn ln(self) -> f64 {
     /// `self.log2()` can produce more accurate results for base 2, and
     /// `self.log10()` can produce more accurate results for base 10.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let five = 5.0_f64;
     ///
@@ -369,6 +403,8 @@ pub fn log(self, base: f64) -> f64 { self.ln() / base.ln() }
 
     /// Returns the base 2 logarithm of the number.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let two = 2.0_f64;
     ///
@@ -390,6 +426,8 @@ pub fn log2(self) -> f64 {
 
     /// Returns the base 10 logarithm of the number.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let ten = 10.0_f64;
     ///
@@ -409,6 +447,8 @@ pub fn log10(self) -> f64 {
     /// * If `self <= other`: `0:0`
     /// * Else: `self - other`
     ///
+    /// # Examples
+    ///
     /// ```
     /// let x = 3.0_f64;
     /// let y = -3.0_f64;
@@ -434,6 +474,8 @@ pub fn abs_sub(self, other: f64) -> f64 {
 
     /// Takes the cubic root of a number.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let x = 8.0_f64;
     ///
@@ -451,6 +493,8 @@ pub fn cbrt(self) -> f64 {
     /// Calculates the length of the hypotenuse of a right-angle triangle given
     /// legs of length `x` and `y`.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let x = 2.0_f64;
     /// let y = 3.0_f64;
@@ -468,6 +512,8 @@ pub fn hypot(self, other: f64) -> f64 {
 
     /// Computes the sine of a number (in radians).
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f64;
     ///
@@ -485,6 +531,8 @@ pub fn sin(self) -> f64 {
 
     /// Computes the cosine of a number (in radians).
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f64;
     ///
@@ -502,6 +550,8 @@ pub fn cos(self) -> f64 {
 
     /// Computes the tangent of a number (in radians).
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f64;
     ///
@@ -520,6 +570,8 @@ pub fn tan(self) -> f64 {
     /// the range [-pi/2, pi/2] or NaN if the number is outside the range
     /// [-1, 1].
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f64;
     ///
@@ -540,6 +592,8 @@ pub fn asin(self) -> f64 {
     /// the range [0, pi] or NaN if the number is outside the range
     /// [-1, 1].
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f64;
     ///
@@ -559,6 +613,8 @@ pub fn acos(self) -> f64 {
     /// Computes the arctangent of a number. Return value is in radians in the
     /// range [-pi/2, pi/2];
     ///
+    /// # Examples
+    ///
     /// ```
     /// let f = 1.0_f64;
     ///
@@ -580,6 +636,8 @@ pub fn atan(self) -> f64 {
     /// * `y >= 0`: `arctan(y/x) + pi` -> `(pi/2, pi]`
     /// * `y < 0`: `arctan(y/x) - pi` -> `(-pi, -pi/2)`
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f64;
     ///
@@ -609,6 +667,8 @@ pub fn atan2(self, other: f64) -> f64 {
     /// Simultaneously computes the sine and cosine of the number, `x`. Returns
     /// `(sin(x), cos(x))`.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f64;
     ///
@@ -630,6 +690,8 @@ pub fn sin_cos(self) -> (f64, f64) {
     /// Returns `e^(self) - 1` in a way that is accurate even if the
     /// number is close to zero.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let x = 7.0_f64;
     ///
@@ -647,6 +709,8 @@ pub fn exp_m1(self) -> f64 {
     /// Returns `ln(1+n)` (natural logarithm) more accurately than if
     /// the operations were performed separately.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f64;
     ///
@@ -665,6 +729,8 @@ pub fn ln_1p(self) -> f64 {
 
     /// Hyperbolic sine function.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f64;
     ///
@@ -686,6 +752,8 @@ pub fn sinh(self) -> f64 {
 
     /// Hyperbolic cosine function.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f64;
     ///
@@ -707,6 +775,8 @@ pub fn cosh(self) -> f64 {
 
     /// Hyperbolic tangent function.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f64;
     ///
@@ -728,6 +798,8 @@ pub fn tanh(self) -> f64 {
 
     /// Inverse hyperbolic sine function.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let x = 1.0_f64;
     /// let f = x.sinh().asinh();
@@ -748,6 +820,8 @@ pub fn asinh(self) -> f64 {
 
     /// Inverse hyperbolic cosine function.
     ///
+    /// # Examples
+    ///
     /// ```
     /// let x = 1.0_f64;
     /// let f = x.cosh().acosh();
@@ -767,6 +841,8 @@ pub fn acosh(self) -> f64 {
 
     /// Inverse hyperbolic tangent function.
     ///
+    /// # Examples
+    ///
     /// ```
     /// use std::f64;
     ///