API docs: macros. Part of #29329 Standard Library Documentation Checklist.

1 files changed, 101 insertions, 21 deletions

diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs
index c426bf8086e..8c7f0fec926 100644
--- a/src/libstd/macros.rs
+++ b/src/libstd/macros.rs
@@ -26,13 +26,33 @@ macro_rules! __rust_unstable_column {
 
 /// The entry point for panic of Rust threads.
 ///
+/// This allows a program to to terminate immediately and provide feedback
+/// to the caller of the program. `panic!` should be used when a program reaches
+/// an unrecoverable problem.
+///
+/// This macro is the perfect way to assert conditions in example code and in
+/// tests.  `panic!` is closely tied with the `unwrap` method of both [`Option`]
+/// and [`Result`][runwrap] enums.  Both implementations call `panic!` when they are set
+/// to None or Err variants.
+///
 /// This macro is used to inject panic into a Rust thread, causing the thread to
 /// panic entirely. Each thread's panic can be reaped as the `Box<Any>` type,
 /// and the single-argument form of the `panic!` macro will be the value which
 /// is transmitted.
 ///
+/// [`Result`] enum is often a better solution for recovering from errors than
+/// using the `panic!` macro.  This macro should be used to avoid proceeding using
+/// incorrect values, such as from external sources.  Detailed information about
+/// error handling is found in the [book].
+///
 /// The multi-argument form of this macro panics with a string and has the
-/// `format!` syntax for building a string.
+/// [`format!`] syntax for building a string.
+///
+/// [runwrap]: ../std/result/enum.Result.html#method.unwrap
+/// [`Option`]: ../std/option/enum.Option.html#method.unwrap
+/// [`Result`]: ../std/result/enum.Result.html
+/// [`format!`]: ../std/macro.format.html
+/// [book]: ../book/second-edition/ch09-01-unrecoverable-errors-with-panic.html
 ///
 /// # Current implementation
 ///
@@ -78,15 +98,19 @@ macro_rules! panic {
 
 /// Macro for printing to the standard output.
 ///
-/// Equivalent to the `println!` macro except that a newline is not printed at
+/// Equivalent to the [`println!`] macro except that a newline is not printed at
 /// the end of the message.
 ///
 /// Note that stdout is frequently line-buffered by default so it may be
-/// necessary to use `io::stdout().flush()` to ensure the output is emitted
+/// necessary to use [`io::stdout().flush()`][flush] to ensure the output is emitted
 /// immediately.
 ///
 /// Use `print!` only for the primary output of your program.  Use
-/// `eprint!` instead to print error and progress messages.
+/// [`eprint!`] instead to print error and progress messages.
+///
+/// [`println!`]: ../std/macro.println.html
+/// [flush]: ../std/io/trait.Write.html#tymethod.flush
+/// [`eprint!`]: ../std/macro.eprint.html
 ///
 /// # Panics
 ///
@@ -118,16 +142,20 @@ macro_rules! print {
     ($($arg:tt)*) => ($crate::io::_print(format_args!($($arg)*)));
 }
 
-/// Macro for printing to the standard output, with a newline. On all
-/// platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone
+/// Macro for printing to the standard output, with a newline.
+///
+/// On all platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone
 /// (no additional CARRIAGE RETURN (`\r`/`U+000D`).
 ///
-/// Use the `format!` syntax to write data to the standard output.
-/// See `std::fmt` for more information.
+/// Use the [`format!`] syntax to write data to the standard output.
+/// See [`std::fmt`] for more information.
 ///
 /// Use `println!` only for the primary output of your program.  Use
-/// `eprintln!` instead to print error and progress messages.
+/// [`eprintln!`] instead to print error and progress messages.
 ///
+/// [`format!`]: ../std/macro.format.html
+/// [`std::fmt`]: ../std/fmt/index.html
+/// [`eprintln!`]: ..std/macro.eprint.html
 /// # Panics
 ///
 /// Panics if writing to `io::stdout` fails.
@@ -149,16 +177,25 @@ macro_rules! println {
 
 /// Macro for printing to the standard error.
 ///
-/// Equivalent to the `print!` macro, except that output goes to
-/// `io::stderr` instead of `io::stdout`.  See `print!` for
+/// Equivalent to the [`print!`] macro, except that output goes to
+/// [`io::stderr`] instead of `io::stdout`.  See [`print!`] for
 /// example usage.
 ///
 /// Use `eprint!` only for error and progress messages.  Use `print!`
 /// instead for the primary output of your program.
 ///
+/// [`io::stderr`]: ../std/io/struct.Stderr.html
+/// [`print!`]: ../std/macro.print.html
+///
 /// # Panics
 ///
 /// Panics if writing to `io::stderr` fails.
+///
+/// # Examples
+///
+/// ```
+/// eprint("Error: Could not complete task");
+/// ```
 #[macro_export]
 #[stable(feature = "eprint", since = "1.19.0")]
 #[allow_internal_unstable]
@@ -168,16 +205,25 @@ macro_rules! eprint {
 
 /// Macro for printing to the standard error, with a newline.
 ///
-/// Equivalent to the `println!` macro, except that output goes to
-/// `io::stderr` instead of `io::stdout`.  See `println!` for
+/// Equivalent to the [`println!`] macro, except that output goes to
+/// [`io::stderr`] instead of `io::stdout`.  See [`println!`] for
 /// example usage.
 ///
 /// Use `eprintln!` only for error and progress messages.  Use `println!`
 /// instead for the primary output of your program.
 ///
+/// [`io::stderr`]: ../std/io/struct.Stderr.html
+/// [`println!`]: ../std/macro.println.html
+///
 /// # Panics
 ///
 /// Panics if writing to `io::stderr` fails.
+///
+/// # Examples
+///
+/// ```
+/// eprint("Error: Could not complete task");
+/// ```
 #[macro_export]
 #[stable(feature = "eprint", since = "1.19.0")]
 macro_rules! eprintln {
@@ -267,13 +313,23 @@ pub mod builtin {
 
     /// The core macro for formatted string creation & output.
     ///
+    /// This macro functions by taking a formatting string literal containing
+    /// `{}` for each additional argument passed.  `format_args!` prepares the
+    /// additional parameters to ensure the output can be interpreted as a string
+    /// and canonicalizes the arguments into a single type.  Any value that implements
+    /// the [`Display`] trait can be passed to `format_args!`, as can any
+    /// [`Debug`] implementation be passed to a `{:?}` within the formatting string.
+    ///
     /// This macro produces a value of type [`fmt::Arguments`]. This value can be
-    /// passed to the functions in [`std::fmt`] for performing useful functions.
+    /// passed to the macros within [`std::fmt`] for performing useful redirection.
     /// All other formatting macros ([`format!`], [`write!`], [`println!`], etc) are
-    /// proxied through this one.
+    /// proxied through this one.  `format_args!`, unlike its derived macros, avoids
+    /// heap allocations.
     ///
     /// For more information, see the documentation in [`std::fmt`].
     ///
+    /// [`Display`]: ../std/fmt/trait.Display.html
+    /// [`Debug`]: ../std/fmt/trait.Debug.html
     /// [`fmt::Arguments`]: ../std/fmt/struct.Arguments.html
     /// [`std::fmt`]: ../std/fmt/index.html
     /// [`format!`]: ../std/macro.format.html
@@ -301,9 +357,11 @@ pub mod builtin {
     /// compile time, yielding an expression of type `&'static str`.
     ///
     /// If the environment variable is not defined, then a compilation error
-    /// will be emitted.  To not emit a compile error, use the `option_env!`
+    /// will be emitted.  To not emit a compile error, use the [`option_env!`]
     /// macro instead.
     ///
+    /// [`option_env!`]: ../std/macro.option_env.html
+    ///
     /// # Examples
     ///
     /// ```
@@ -319,11 +377,14 @@ pub mod builtin {
     /// If the named environment variable is present at compile time, this will
     /// expand into an expression of type `Option<&'static str>` whose value is
     /// `Some` of the value of the environment variable. If the environment
-    /// variable is not present, then this will expand to `None`.
+    /// variable is not present, then this will expand to `None`.  See
+    /// [`Option<T>`][option] for more information on this type.
     ///
     /// A compile time error is never emitted when using this macro regardless
     /// of whether the environment variable is present or not.
     ///
+    /// [option]: ../std/option/enum.Option.html
+    ///
     /// # Examples
     ///
     /// ```
@@ -385,10 +446,16 @@ pub mod builtin {
 
     /// A macro which expands to the line number on which it was invoked.
     ///
+    /// With [`column!`] and [`file!`], these macros provide debugging information for
+    /// developers about the location within the source.
+    ///
     /// The expanded expression has type `u32`, and the returned line is not
     /// the invocation of the `line!()` macro itself, but rather the first macro
     /// invocation leading up to the invocation of the `line!()` macro.
     ///
+    /// [`column!`]: macro.column.html
+    /// [`file!`]: macro.file.html
+    ///
     /// # Examples
     ///
     /// ```
@@ -401,9 +468,15 @@ pub mod builtin {
 
     /// A macro which expands to the column number on which it was invoked.
     ///
+    /// With [`line!`] and [`file!`], these macros provide debugging information for
+    /// developers about the location within the source.
+    ///
     /// The expanded expression has type `u32`, and the returned column is not
-    /// the invocation of the `column!()` macro itself, but rather the first macro
-    /// invocation leading up to the invocation of the `column!()` macro.
+    /// the invocation of the `column!` macro itself, but rather the first macro
+    /// invocation leading up to the invocation of the `column!` macro.
+    ///
+    /// [`line!`]: macro.line.html
+    /// [`file!`]: macro.file.html
     ///
     /// # Examples
     ///
@@ -417,11 +490,18 @@ pub mod builtin {
 
     /// A macro which expands to the file name from which it was invoked.
     ///
+    /// With [`line!`] and [`column!`], these macros provide debugging information for
+    /// developers about the location within the source.
+    ///
+    ///
     /// The expanded expression has type `&'static str`, and the returned file
-    /// is not the invocation of the `file!()` macro itself, but rather the
-    /// first macro invocation leading up to the invocation of the `file!()`
+    /// is not the invocation of the `file!` macro itself, but rather the
+    /// first macro invocation leading up to the invocation of the `file!`
     /// macro.
     ///
+    /// [`line!`]: macro.line.html
+    /// [`column!`]: macro.column.html
+    ///
     /// # Examples
     ///
     /// ```