Open
Description
openedon Nov 3, 2020
People will often use the # character to hide lines that aren't relevant to the example, but rustdoc will display blank lines you leave between #-prefixed lines and the visible lines. For example, this source:
//! ```
//! # #[cfg(any(feature = "alloc", feature = "std"))]
//! # mod test {
//!
//! use num::FromPrimitive;
//! use num::bigint::BigInt;
//! use num::rational::{Ratio, BigRational};
//!
//! # pub
//! fn approx_sqrt(number: u64, iterations: usize) -> BigRational {
//! let start: Ratio<BigInt> = Ratio::from_integer(FromPrimitive::from_u64(number).unwrap());
//! let mut approx = start.clone();
//!
//! for _ in 0..iterations {
//! approx = (&approx + (&start / &approx)) /
//! Ratio::from_integer(FromPrimitive::from_u64(2).unwrap());
//! }
//!
//! approx
//! }
//! # }
//! # #[cfg(not(any(feature = "alloc", feature = "std")))]
//! # mod test { pub fn approx_sqrt(n: u64, _: usize) -> u64 { n } }
//! # use crate::test::approx_sqrt;
//!
//! fn main() {
//! println!("{}", approx_sqrt(10, 4)); // prints 4057691201/1283082416
//! }
//!
//! ```leads to this output:
I propose that rustdoc strips blank lines from the start and end of code blocks to avoid this not-great-looking output. This would happen after the # lines were stripped out.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment