Fix doc warnings and link failures (#1948)

Also add configuration to CI to fail doc generation if any links are
broken. Unfortunately we can't blanket deny all warnings in rustdoc
since some are unconditional warnings, but for now this is hopefully
good enough.

Closes #1947

.github/workflows/main.yml

@@ -49,6 +49,8 @@ jobs:
   doc_api:
     name: Doc - build the API documentation
     runs-on: ubuntu-latest
+    env:
+      RUSTDOCFLAGS: -Dintra-doc-link-resolution-failure
     steps:
     - uses: actions/checkout@v2
       with:

cranelift/codegen/src/ir/extfunc.rs

@@ -383,7 +383,7 @@ pub struct ExtFuncData {
     /// flag is best used when the target is known to be in the same unit of code generation, such
     /// as a Wasm module.
     ///
-    /// See the documentation for [`RelocDistance`](machinst::RelocDistance) for more details. A
+    /// See the documentation for [`RelocDistance`](crate::machinst::RelocDistance) for more details. A
     /// `colocated` flag value of `true` implies `RelocDistance::Near`.
     pub colocated: bool,
 }

cranelift/codegen/src/ir/globalvalue.rs

@@ -66,7 +66,7 @@ pub enum GlobalValueData {
         ///
         /// If `true`, some backends may use relocation forms that have limited range: for example,
         /// a +/- 2^27-byte range on AArch64. See the documentation for
-        /// [`RelocDistance`](machinst::RelocDistance) for more details.
+        /// [`RelocDistance`](crate::machinst::RelocDistance) for more details.
         colocated: bool,
 
         /// Does this symbol refer to a thread local storage value?

cranelift/codegen/src/isa/aarch64/abi.rs

@@ -86,9 +86,9 @@
 //!   formal arguments, would:
 //!   - Accept a pointer P to the struct return area in x0 on entry.
 //!   - Return v3 in x0.
-//!   - Return v2 in memory at [P].
+//!   - Return v2 in memory at `[P]`.
-//!   - Return v1 in memory at [P+8].
+//!   - Return v1 in memory at `[P+8]`.
-//!   - Return v0 in memory at [P+16].
+//!   - Return v0 in memory at `[P+16]`.
 
 use crate::ir;
 use crate::ir::types;

cranelift/codegen/src/machinst/buffer.rs

@@ -12,13 +12,13 @@
 //!   from the branch itself.
 //!
 //! - The lowering of control flow from the CFG-with-edges produced by
-//!   [BlockLoweringOrder], combined with many empty edge blocks when the register
+//!   [BlockLoweringOrder](super::BlockLoweringOrder), combined with many empty
-//!   allocator does not need to insert any spills/reloads/moves in edge blocks,
+//!   edge blocks when the register allocator does not need to insert any
-//!   results in many suboptimal branch patterns. The lowering also pays no
+//!   spills/reloads/moves in edge blocks, results in many suboptimal branch
-//!   attention to block order, and so two-target conditional forms (cond-br
+//!   patterns. The lowering also pays no attention to block order, and so
-//!   followed by uncond-br) can often by avoided because one of the targets is
+//!   two-target conditional forms (cond-br followed by uncond-br) can often by
-//!   the fallthrough. There are several cases here where we can simplify to use
+//!   avoided because one of the targets is the fallthrough. There are several
-//!   fewer branches.
+//!   cases here where we can simplify to use fewer branches.
 //!
 //! This "buffer" implements a single-pass code emission strategy (with a later
 //! "fixup" pass, but only through recorded fixups, not all instructions). The
@@ -41,7 +41,7 @@
 //!   by the emitter (e.g., vcode iterating over instruction structs). The emitter
 //!   has some awareness of this: it either asks for an island between blocks, so
 //!   it is not accidentally executed, or else it emits a branch around the island
-//!   when all other options fail (see [Inst::EmitIsland] meta-instruction).
+//!   when all other options fail (see `Inst::EmitIsland` meta-instruction).
 //!
 //! - A "veneer" is an instruction (or sequence of instructions) in an "island"
 //!   that implements a longer-range reference to a label. The idea is that, for

cranelift/filetests/src/function_runner.rs

@@ -39,7 +39,8 @@ pub struct SingleFunctionCompiler {
 
 impl SingleFunctionCompiler {
     /// Build a [SingleFunctionCompiler] from a [TargetIsa]. For functions to be runnable on the
-    /// host machine, this [TargetISA] must match the host machine's ISA (see [with_host_isa]).
+    /// host machine, this [TargetIsa] must match the host machine's ISA (see
+    /// [SingleFunctionCompiler::with_host_isa]).
     pub fn new(isa: Box<dyn TargetIsa>) -> Self {
         let trampolines = HashMap::new();
         Self { isa, trampolines }

cranelift/filetests/src/test_interpret.rs

@@ -1,6 +1,7 @@
 //! Test command for interpreting CLIF files and verifying their results
 //!
-//! The `interpret` test command interprets each function on the host machine using [RunCommand]s.
+//! The `interpret` test command interprets each function on the host machine
+//! using [RunCommand](cranelift_reader::RunCommand)s.
 
 use crate::subtest::{Context, SubTest, SubtestResult};
 use cranelift_codegen::{self, ir};

cranelift/peepmatic/crates/runtime/src/optimizer.rs

@@ -16,7 +16,7 @@ use std::num::NonZeroU32;
 /// optimizations to instructions.
 ///
 /// These are created from a set of peephole optimizations with the
-/// [`PeepholeOptimizer::instance`][crate::PeepholeOptimizer::instance] method.
+/// [`PeepholeOptimizations::optimizer`] method.
 ///
 /// Reusing an instance when applying peephole optimizations to different
 /// instruction sequences means that you reuse internal allocations that are

crates/runtime/src/externref.rs

@@ -21,7 +21,7 @@
 //! The `VMExternData` struct is *preceded* by the dynamically-sized value boxed
 //! up and referenced by one or more `VMExternRef`s:
 //!
-//! ```ignore
+//! ```text
 //!      ,-------------------------------------------------------.
 //!      |                                                       |
 //!      V                                                       |

crates/wiggle/src/lib.rs

@@ -61,7 +61,7 @@ pub use region::Region;
 /// See the safety guarantees of [`BorrowChecker`], which asserts that exactly
 /// one `BorrowChecker` may be constructed for each WebAssembly memory.
 ///
-/// The [`GuestMemory::as_slice`] or [`GuestPtr::as_str`] will return smart
+/// The [`GuestPtr::as_slice`] or [`GuestPtr::as_str`] will return smart
 /// pointers [`GuestSlice`] and [`GuestStr`]. These types, which implement
 /// [`std::ops::Deref`] and [`std::ops::DerefMut`], provide mutable references
 /// into the memory region given by a `GuestMemory`.

crates/wiggle/wasmtime/macro/src/lib.rs

@@ -21,7 +21,7 @@ use config::{MissingMemoryConf, ModuleConf, TargetConf};
 ///   where the macro is invoked. `witx_literal` takes a string of the witx document, e.g.
 ///   `"(typename $foo u8)"`.
 /// * `ctx`: The context struct used for the Wiggle implementation. This must be the same
-///   type as the [`wasmtime_wiggle::from_witx`] macro at `target` was invoked with. However, it
+///   type as the `wasmtime_wiggle::from_witx` macro at `target` was invoked with. However, it
 ///   must be imported to the current scope so that it is a bare identifier e.g. `CtxType`, not
 ///   `path::to::CtxType`.
 /// * `modules`: Describes how any modules in the witx document will be implemented as Wasmtime