Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Run rust-fmt On Doc Comments #104058

Closed
wants to merge 2 commits into from
Closed

Run rust-fmt On Doc Comments #104058

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6391128
Automated rustfmt format doc comments
AldaronLau Nov 6, 2022
9093c7e
Undo changes caused by nightly rustfmt bugs
AldaronLau Nov 6, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 11 additions & 14 deletions library/alloc/src/borrow.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,11 +145,17 @@ where
/// ```
/// use std::borrow::Cow;
///
/// struct Items<'a, X: 'a> where [X]: ToOwned<Owned = Vec<X>> {
/// struct Items<'a, X: 'a>
/// where
/// [X]: ToOwned<Owned = Vec<X>>,
/// {
/// values: Cow<'a, [X]>,
/// }
///
/// impl<'a, X: Clone + 'a> Items<'a, X> where [X]: ToOwned<Owned = Vec<X>> {
/// impl<'a, X: Clone + 'a> Items<'a, X>
/// where
/// [X]: ToOwned<Owned = Vec<X>>,
/// {
/// fn new(v: Cow<'a, [X]>) -> Self {
/// Items { values: v }
/// }
Expand Down Expand Up @@ -265,10 +271,7 @@ impl<B: ?Sized + ToOwned> Cow<'_, B> {
/// let mut cow = Cow::Borrowed("foo");
/// cow.to_mut().make_ascii_uppercase();
///
/// assert_eq!(
/// cow,
/// Cow::Owned(String::from("FOO")) as Cow<str>
/// );
/// assert_eq!(cow, Cow::Owned(String::from("FOO")) as Cow<str>);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn to_mut(&mut self) -> &mut <B as ToOwned>::Owned {
Expand Down Expand Up @@ -298,10 +301,7 @@ impl<B: ?Sized + ToOwned> Cow<'_, B> {
/// let s = "Hello world!";
/// let cow = Cow::Borrowed(s);
///
/// assert_eq!(
/// cow.into_owned(),
/// String::from(s)
/// );
/// assert_eq!(cow.into_owned(), String::from(s));
/// ```
///
/// Calling `into_owned` on a `Cow::Owned` returns the owned data. The data is moved out of the
Expand All @@ -313,10 +313,7 @@ impl<B: ?Sized + ToOwned> Cow<'_, B> {
/// let s = "Hello world!";
/// let cow: Cow<str> = Cow::Owned(String::from(s));
///
/// assert_eq!(
/// cow.into_owned(),
/// String::from(s)
/// );
/// assert_eq!(cow.into_owned(), String::from(s));
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn into_owned(self) -> <B as ToOwned>::Owned {
Expand Down
16 changes: 6 additions & 10 deletions library/alloc/src/boxed.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2246,8 +2246,7 @@ impl<'a, E: Error + Send + Sync + 'a> From<E> for Box<dyn Error + Send + Sync +
/// let an_error = AnError;
/// assert!(0 == mem::size_of_val(&an_error));
/// let a_boxed_error = Box::<dyn Error + Send + Sync>::from(an_error);
/// assert!(
/// mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
/// assert!(mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
/// ```
fn from(err: E) -> Box<dyn Error + Send + Sync + 'a> {
Box::new(err)
Expand All @@ -2267,8 +2266,7 @@ impl From<String> for Box<dyn Error + Send + Sync> {
///
/// let a_string_error = "a string error".to_string();
/// let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_string_error);
/// assert!(
/// mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
/// assert!(mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
/// ```
#[inline]
fn from(err: String) -> Box<dyn Error + Send + Sync> {
Expand Down Expand Up @@ -2335,8 +2333,7 @@ impl<'a> From<&str> for Box<dyn Error + Send + Sync + 'a> {
///
/// let a_str_error = "a str error";
/// let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_str_error);
/// assert!(
/// mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
/// assert!(mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
/// ```
#[inline]
fn from(err: &str) -> Box<dyn Error + Send + Sync + 'a> {
Expand Down Expand Up @@ -2374,14 +2371,13 @@ impl<'a, 'b> From<Cow<'b, str>> for Box<dyn Error + Send + Sync + 'a> {
/// # Examples
///
/// ```
/// use std::borrow::Cow;
/// use std::error::Error;
/// use std::mem;
/// use std::borrow::Cow;
///
/// let a_cow_str_error = Cow::from("a str error");
/// let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_cow_str_error);
/// assert!(
/// mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
/// assert!(mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
/// ```
fn from(err: Cow<'b, str>) -> Box<dyn Error + Send + Sync + 'a> {
From::from(String::from(err))
Expand All @@ -2396,9 +2392,9 @@ impl<'a> From<Cow<'a, str>> for Box<dyn Error> {
/// # Examples
///
/// ```
/// use std::borrow::Cow;
/// use std::error::Error;
/// use std::mem;
/// use std::borrow::Cow;
///
/// let a_cow_str_error = Cow::from("a str error");
/// let a_boxed_error = Box::<dyn Error>::from(a_cow_str_error);
Expand Down
27 changes: 13 additions & 14 deletions library/alloc/src/collections/binary_heap.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,7 @@
//! // Notice that the we flip the ordering on costs.
//! // In case of a tie we compare positions - this step is necessary
//! // to make implementations of `PartialEq` and `Ord` consistent.
//! other.cost.cmp(&self.cost)
//! .then_with(|| self.position.cmp(&other.position))
//! other.cost.cmp(&self.cost).then_with(|| self.position.cmp(&other.position))
//! }
//! }
//!
Expand Down Expand Up @@ -71,10 +70,14 @@
//! // Examine the frontier with lower cost nodes first (min-heap)
//! while let Some(State { cost, position }) = heap.pop() {
//! // Alternatively we could have continued to find all shortest paths
//! if position == goal { return Some(cost); }
//! if position == goal {
//! return Some(cost);
//! }
//!
//! // Important as we may have already found a better way
//! if cost > dist[position] { continue; }
//! if cost > dist[position] {
//! continue;
//! }
//!
//! // For each node we can reach, see if we can find a way with
//! // a lower cost going through this node
Expand Down Expand Up @@ -118,19 +121,16 @@
//! // Chosen for its efficiency.
//! let graph = vec![
//! // Node 0
//! vec![Edge { node: 2, cost: 10 },
//! Edge { node: 1, cost: 1 }],
//! vec![Edge { node: 2, cost: 10 }, Edge { node: 1, cost: 1 }],
//! // Node 1
//! vec![Edge { node: 3, cost: 2 }],
//! // Node 2
//! vec![Edge { node: 1, cost: 1 },
//! Edge { node: 3, cost: 3 },
//! Edge { node: 4, cost: 1 }],
//! vec![Edge { node: 1, cost: 1 }, Edge { node: 3, cost: 3 }, Edge { node: 4, cost: 1 }],
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like this is using rustc's rustfmt settings including use_small_heuristics = "Max". I think default settings would be more appropriate for library docs. But maybe that's getting too picky.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be tricky to do that without splitting the code blocks into their own files and include them (which I'm happy to try, if that would be an acceptable solution). An alternate solution would to instead add rustfmt file(s) for the rust library directories (but then it's applied across the libraries outside of doc comments). I don't think having specific format settings for docs is something that's even planned in rustfmt.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be tricky to do that without splitting the code blocks into their own files and include them (which I'm happy to try, if that would be an acceptable solution).

That would make updating documentation along with functions more tedious and easy to miss. Some macro-generated code already contains lots of annotations, an include could be easily missed.

An alternate solution would to instead add rustfmt file(s) for the rust library directories (but then it's applied across the libraries outside of doc comments).

That'd lead to reformatting all of the library code, no?

I don't think having specific format settings for docs is something that's even planned in rustfmt.

Well, if we decide that doc comment examples need different formatting then something like that might be necessary.

//! // Node 3
//! vec![Edge { node: 0, cost: 7 },
//! Edge { node: 4, cost: 2 }],
//! vec![Edge { node: 0, cost: 7 }, Edge { node: 4, cost: 2 }],
//! // Node 4
//! vec![]];
//! vec![],
//! ];
//!
//! assert_eq!(shortest_path(&graph, 0, 1), Some(1));
//! assert_eq!(shortest_path(&graph, 0, 3), Some(3));
Expand Down Expand Up @@ -229,8 +229,8 @@ mod tests;
/// value instead of the greatest one.
///
/// ```
/// use std::collections::BinaryHeap;
/// use std::cmp::Reverse;
/// use std::collections::BinaryHeap;
///
/// let mut heap = BinaryHeap::new();
///
Expand Down Expand Up @@ -877,7 +877,6 @@ impl<T> BinaryHeap<T> {
/// heap.push(5);
/// heap.push(2);
/// assert_eq!(heap.peek(), Some(&5));
///
/// ```
///
/// # Time complexity
Expand Down
34 changes: 12 additions & 22 deletions library/alloc/src/collections/btree/map.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,15 +89,14 @@ pub(super) const MIN_LEN: usize = node::MIN_LEN_AFTER_SPLIT;
/// let mut movie_reviews = BTreeMap::new();
///
/// // review some movies.
/// movie_reviews.insert("Office Space", "Deals with real issues in the workplace.");
/// movie_reviews.insert("Pulp Fiction", "Masterpiece.");
/// movie_reviews.insert("The Godfather", "Very enjoyable.");
/// movie_reviews.insert("Office Space", "Deals with real issues in the workplace.");
/// movie_reviews.insert("Pulp Fiction", "Masterpiece.");
/// movie_reviews.insert("The Godfather", "Very enjoyable.");
/// movie_reviews.insert("The Blues Brothers", "Eye lyked it a lot.");
///
/// // check for a specific one.
/// if !movie_reviews.contains_key("Les Misérables") {
/// println!("We've got {} reviews, but Les Misérables ain't one.",
/// movie_reviews.len());
/// println!("We've got {} reviews, but Les Misérables ain't one.", movie_reviews.len());
/// }
///
/// // oops, this review has a lot of spelling mistakes, let's delete it.
Expand All @@ -107,8 +106,8 @@ pub(super) const MIN_LEN: usize = node::MIN_LEN_AFTER_SPLIT;
/// let to_find = ["Up!", "Office Space"];
/// for movie in &to_find {
/// match movie_reviews.get(movie) {
/// Some(review) => println!("{movie}: {review}"),
/// None => println!("{movie} is unreviewed.")
/// Some(review) => println!("{movie}: {review}"),
/// None => println!("{movie} is unreviewed."),
/// }
/// }
///
Expand All @@ -126,12 +125,8 @@ pub(super) const MIN_LEN: usize = node::MIN_LEN_AFTER_SPLIT;
/// ```
/// use std::collections::BTreeMap;
///
/// let solar_distance = BTreeMap::from([
/// ("Mercury", 0.4),
/// ("Venus", 0.7),
/// ("Earth", 1.0),
/// ("Mars", 1.5),
/// ]);
/// let solar_distance =
/// BTreeMap::from([("Mercury", 0.4), ("Venus", 0.7), ("Earth", 1.0), ("Mars", 1.5)]);
/// ```
///
/// `BTreeMap` implements an [`Entry API`], which allows for complex
Expand Down Expand Up @@ -622,8 +617,8 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
/// ```
/// # #![feature(allocator_api)]
/// # #![feature(btreemap_alloc)]
/// use std::collections::BTreeMap;
/// use std::alloc::Global;
/// use std::collections::BTreeMap;
///
/// let mut map = BTreeMap::new_in(Global);
///
Expand Down Expand Up @@ -1076,7 +1071,7 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
/// ```
/// use std::collections::BTreeMap;
///
/// let mut map: BTreeMap<i32, i32> = (0..8).map(|x| (x, x*10)).collect();
/// let mut map: BTreeMap<i32, i32> = (0..8).map(|x| (x, x * 10)).collect();
/// // Keep only the elements with even-numbered keys.
/// map.retain(|&k, _| k % 2 == 0);
/// assert!(map.into_iter().eq(vec![(0, 0), (2, 20), (4, 40), (6, 60)]));
Expand Down Expand Up @@ -2281,11 +2276,7 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
/// ```
/// use std::collections::BTreeMap;
///
/// let mut map = BTreeMap::from([
/// ("a", 1),
/// ("b", 2),
/// ("c", 3),
/// ]);
/// let mut map = BTreeMap::from([("a", 1), ("b", 2), ("c", 3)]);
///
/// // add 10 to the value if the key isn't "a"
/// for (key, value) in map.iter_mut() {
Expand Down Expand Up @@ -2365,8 +2356,7 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
/// }
///
/// let values: Vec<String> = a.values().cloned().collect();
/// assert_eq!(values, [String::from("hello!"),
/// String::from("goodbye!")]);
/// assert_eq!(values, [String::from("hello!"), String::from("goodbye!")]);
/// ```
#[stable(feature = "map_values_mut", since = "1.10.0")]
pub fn values_mut(&mut self) -> ValuesMut<'_, K, V> {
Expand Down
24 changes: 10 additions & 14 deletions library/alloc/src/collections/btree/map/entry.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -246,14 +246,10 @@ impl<'a, K: Ord, V, A: Allocator + Clone> Entry<'a, K, V, A> {
///
/// let mut map: BTreeMap<&str, usize> = BTreeMap::new();
///
/// map.entry("poneyland")
/// .and_modify(|e| { *e += 1 })
/// .or_insert(42);
/// map.entry("poneyland").and_modify(|e| *e += 1).or_insert(42);
/// assert_eq!(map["poneyland"], 42);
///
/// map.entry("poneyland")
/// .and_modify(|e| { *e += 1 })
/// .or_insert(42);
/// map.entry("poneyland").and_modify(|e| *e += 1).or_insert(42);
/// assert_eq!(map["poneyland"], 43);
/// ```
#[stable(feature = "entry_and_modify", since = "1.26.0")]
Expand Down Expand Up @@ -316,8 +312,8 @@ impl<'a, K: Ord, V, A: Allocator + Clone> VacantEntry<'a, K, V, A> {
/// # Examples
///
/// ```
/// use std::collections::BTreeMap;
/// use std::collections::btree_map::Entry;
/// use std::collections::BTreeMap;
///
/// let mut map: BTreeMap<&str, usize> = BTreeMap::new();
///
Expand All @@ -336,8 +332,8 @@ impl<'a, K: Ord, V, A: Allocator + Clone> VacantEntry<'a, K, V, A> {
/// # Examples
///
/// ```
/// use std::collections::BTreeMap;
/// use std::collections::btree_map::Entry;
/// use std::collections::BTreeMap;
///
/// let mut map: BTreeMap<&str, u32> = BTreeMap::new();
///
Expand Down Expand Up @@ -406,8 +402,8 @@ impl<'a, K: Ord, V, A: Allocator + Clone> OccupiedEntry<'a, K, V, A> {
/// # Examples
///
/// ```
/// use std::collections::BTreeMap;
/// use std::collections::btree_map::Entry;
/// use std::collections::BTreeMap;
///
/// let mut map: BTreeMap<&str, usize> = BTreeMap::new();
/// map.entry("poneyland").or_insert(12);
Expand All @@ -430,8 +426,8 @@ impl<'a, K: Ord, V, A: Allocator + Clone> OccupiedEntry<'a, K, V, A> {
/// # Examples
///
/// ```
/// use std::collections::BTreeMap;
/// use std::collections::btree_map::Entry;
/// use std::collections::BTreeMap;
///
/// let mut map: BTreeMap<&str, usize> = BTreeMap::new();
/// map.entry("poneyland").or_insert(12);
Expand All @@ -456,8 +452,8 @@ impl<'a, K: Ord, V, A: Allocator + Clone> OccupiedEntry<'a, K, V, A> {
/// # Examples
///
/// ```
/// use std::collections::BTreeMap;
/// use std::collections::btree_map::Entry;
/// use std::collections::BTreeMap;
///
/// let mut map: BTreeMap<&str, usize> = BTreeMap::new();
/// map.entry("poneyland").or_insert(12);
Expand Down Expand Up @@ -486,8 +482,8 @@ impl<'a, K: Ord, V, A: Allocator + Clone> OccupiedEntry<'a, K, V, A> {
/// # Examples
///
/// ```
/// use std::collections::BTreeMap;
/// use std::collections::btree_map::Entry;
/// use std::collections::BTreeMap;
///
/// let mut map: BTreeMap<&str, usize> = BTreeMap::new();
/// map.entry("poneyland").or_insert(12);
Expand All @@ -510,8 +506,8 @@ impl<'a, K: Ord, V, A: Allocator + Clone> OccupiedEntry<'a, K, V, A> {
/// # Examples
///
/// ```
/// use std::collections::BTreeMap;
/// use std::collections::btree_map::Entry;
/// use std::collections::BTreeMap;
///
/// let mut map: BTreeMap<&str, usize> = BTreeMap::new();
/// map.entry("poneyland").or_insert(12);
Expand All @@ -531,8 +527,8 @@ impl<'a, K: Ord, V, A: Allocator + Clone> OccupiedEntry<'a, K, V, A> {
/// # Examples
///
/// ```
/// use std::collections::BTreeMap;
/// use std::collections::btree_map::Entry;
/// use std::collections::BTreeMap;
///
/// let mut map: BTreeMap<&str, usize> = BTreeMap::new();
/// map.entry("poneyland").or_insert(12);
Expand Down
5 changes: 2 additions & 3 deletions library/alloc/src/collections/btree/set.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,7 @@ use crate::alloc::{Allocator, Global};
///
/// // Check for a specific one.
/// if !books.contains("The Winds of Winter") {
/// println!("We have {} books, but The Winds of Winter ain't one.",
/// books.len());
/// println!("We have {} books, but The Winds of Winter ain't one.", books.len());
/// }
///
/// // Remove a book.
Expand Down Expand Up @@ -359,8 +358,8 @@ impl<T, A: Allocator + Clone> BTreeSet<T, A> {
/// # #![allow(unused_mut)]
/// # #![feature(allocator_api)]
/// # #![feature(btreemap_alloc)]
/// use std::collections::BTreeSet;
/// use std::alloc::Global;
/// use std::collections::BTreeSet;
///
/// let mut set: BTreeSet<i32> = BTreeSet::new_in(Global);
/// ```
Expand Down
Loading