Introduce "wrapper" helpers to rustdoc

Author: yotamofek

src/librustdoc/clean/cfg.rs

@@ -3,16 +3,16 @@
 // FIXME: Once the portability lint RFC is implemented (see tracking issue #41619),
 // switch to use those structures instead.
 
-use std::fmt::{self, Write};
-use std::{mem, ops};
+use std::{fmt, mem, ops};
 
+use itertools::Either;
 use rustc_ast::{LitKind, MetaItem, MetaItemInner, MetaItemKind, MetaItemLit};
 use rustc_data_structures::fx::FxHashSet;
 use rustc_session::parse::ParseSess;
 use rustc_span::Span;
 use rustc_span::symbol::{Symbol, sym};
 
-use crate::display::Joined as _;
+use crate::display::{Joined as _, MaybeDisplay, Parentheses, Wrappers as _};
 use crate::html::escape::Escape;
 
 #[cfg(test)]
@@ -376,27 +376,20 @@ impl Format {
             Format::LongPlain => false,
         }
     }
+
+    fn escape(self, s: &str) -> impl fmt::Display {
+        if self.is_html() { Either::Left(Escape(s)) } else { Either::Right(s) }
+    }
 }
 
 /// Pretty-print wrapper for a `Cfg`. Also indicates what form of rendering should be used.
 struct Display<'a>(&'a Cfg, Format);
 
-fn write_with_opt_paren<T: fmt::Display>(
-    fmt: &mut fmt::Formatter<'_>,
-    has_paren: bool,
-    obj: T,
-) -> fmt::Result {
-    if has_paren {
-        fmt.write_char('(')?;
-    }
-    obj.fmt(fmt)?;
-    if has_paren {
-        fmt.write_char(')')?;
+impl Display<'_> {
+    fn code_wrappers(&self) -> (&'static str, &'static str) {
+        if self.1.is_html() { ("<code>", "</code>") } else { ("`", "`") }
     }
-    Ok(())
-}
 
-impl Display<'_> {
     fn display_sub_cfgs(
         &self,
         fmt: &mut fmt::Formatter<'_>,
@@ -427,20 +420,17 @@ impl Display<'_> {
             sub_cfgs
                 .iter()
                 .map(|sub_cfg| {
-                    fmt::from_fn(move |fmt| {
-                        if let Cfg::Cfg(_, Some(feat)) = sub_cfg
-                            && short_longhand
-                        {
-                            if self.1.is_html() {
-                                write!(fmt, "<code>{feat}</code>")?;
-                            } else {
-                                write!(fmt, "`{feat}`")?;
-                            }
-                        } else {
-                            write_with_opt_paren(fmt, !sub_cfg.is_all(), Display(sub_cfg, self.1))?;
-                        }
-                        Ok(())
-                    })
+                    if let Cfg::Cfg(_, Some(feat)) = sub_cfg
+                        && short_longhand
+                    {
+                        Either::Left(self.code_wrappers().wrap(feat))
+                    } else {
+                        Either::Right(
+                            (!sub_cfg.is_all())
+                                .then_some(Parentheses)
+                                .wrap(Display(sub_cfg, self.1)),
+                        )
+                    }
                 })
                 .joined(separator, f)
         })
@@ -461,9 +451,7 @@ impl fmt::Display for Display<'_> {
                 sub_cfgs
                     .iter()
                     .map(|sub_cfg| {
-                        fmt::from_fn(|fmt| {
-                            write_with_opt_paren(fmt, !sub_cfg.is_all(), Display(sub_cfg, self.1))
-                        })
+                        (!sub_cfg.is_all()).then_some(Parentheses).wrap(Display(sub_cfg, self.1))
                     })
                     .joined(separator, fmt)
             }
@@ -568,21 +556,13 @@ impl fmt::Display for Display<'_> {
                 };
                 if !human_readable.is_empty() {
                     fmt.write_str(human_readable)
-                } else if let Some(v) = value {
-                    if self.1.is_html() {
-                        write!(
-                            fmt,
-                            r#"<code>{}="{}"</code>"#,
-                            Escape(name.as_str()),
-                            Escape(v.as_str())
-                        )
-                    } else {
-                        write!(fmt, r#"`{name}="{v}"`"#)
-                    }
-                } else if self.1.is_html() {
-                    write!(fmt, "<code>{}</code>", Escape(name.as_str()))
                 } else {
-                    write!(fmt, "`{name}`")
+                    let value = value
+                        .map(|v| fmt::from_fn(move |f| write!(f, "={}", self.1.escape(v.as_str()))))
+                        .maybe_display();
+                    self.code_wrappers()
+                        .wrap(format_args!("{}{value}", self.1.escape(name.as_str())))
+                        .fmt(fmt)
                 }
             }
         }

src/librustdoc/display.rs

@@ -1,6 +1,6 @@
 //! Various utilities for working with [`fmt::Display`] implementations.
 
-use std::fmt::{self, Display, Formatter};
+use std::fmt::{self, Display, Formatter, Write as _};
 
 pub(crate) trait Joined: IntoIterator {
     /// Takes an iterator over elements that implement [`Display`], and format them into `f`, separated by `sep`.
@@ -45,3 +45,93 @@ impl<T: Display> MaybeDisplay for Option<T> {
         })
     }
 }
+
+pub(crate) trait Wrappers: Sized {
+    fn prefix(&self) -> impl Display;
+    fn suffix(&self) -> impl Display;
+
+    fn wrap<T: Display>(self, wrapped: T) -> impl Display {
+        fmt::from_fn(move |f| {
+            self.prefix().fmt(f)?;
+            wrapped.fmt(f)?;
+            self.suffix().fmt(f)?;
+            Ok(())
+        })
+    }
+
+    fn wrap_fn(self, fmt: impl Fn(&mut Formatter<'_>) -> fmt::Result) -> impl Display {
+        self.wrap(fmt::from_fn(fmt))
+    }
+}
+
+impl<W: Wrappers> Wrappers for Option<W> {
+    fn prefix(&self) -> impl Display {
+        self.as_ref().map(W::prefix).maybe_display()
+    }
+
+    fn suffix(&self) -> impl Display {
+        self.as_ref().map(W::suffix).maybe_display()
+    }
+}
+
+pub(crate) trait Wrapped: Display + Sized {
+    fn wrapped(self, wrappers: impl Wrappers) -> impl Display {
+        wrappers.wrap(self)
+    }
+}
+
+impl<T> Wrapped for T where T: Display + Sized {}
+
+impl<Prefix: Display, Suffix: Display> Wrappers for (Prefix, Suffix) {
+    fn prefix(&self) -> impl Display {
+        &self.0
+    }
+
+    fn suffix(&self) -> impl Display {
+        &self.1
+    }
+}
+
+macro_rules! impl_wrappers {
+    ($vis:vis struct $name:ident($prefix:literal, $suffix:literal)) => {
+        #[derive(Clone, Copy)]
+        $vis struct $name;
+
+        impl Wrappers for $name {
+            fn prefix(&self) -> impl Display {
+                $prefix
+            }
+
+            fn suffix(&self) -> impl Display {
+                $suffix
+            }
+        }
+    }
+}
+
+impl_wrappers!(pub(crate) struct Parentheses('(', ')'));
+impl_wrappers!(pub(crate) struct SquareBrackets('[', ']'));
+
+pub(crate) struct AngleBrackets;
+
+impl Wrappers for AngleBrackets {
+    fn prefix(&self) -> impl Display {
+        fmt::from_fn(|f| if f.alternate() { f.write_char('<') } else { f.write_str("&lt;") })
+    }
+
+    fn suffix(&self) -> impl Display {
+        fmt::from_fn(|f| if f.alternate() { f.write_char('>') } else { f.write_str("&gt;") })
+    }
+}
+
+pub(crate) trait InheritOpts: Display + Sized {
+    fn inherit_opts(self, f: &Formatter<'_>) -> impl Display + use<Self> {
+        let options = f.options();
+        fmt::from_fn(move |f| {
+            let mut f = f.with_options(options);
+            self.fmt(&mut f)
+        })
+    }
+}
+
+impl<T: Display + Sized> InheritOpts for T {}