From 0acd2072c225552c17d0d09466231287d286b35d Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Tue, 30 Jun 2020 13:01:49 -0500 Subject: [PATCH] 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 | 2 ++ cranelift/codegen/src/ir/extfunc.rs | 2 +- cranelift/codegen/src/ir/globalvalue.rs | 2 +- cranelift/codegen/src/isa/aarch64/abi.rs | 6 +++--- cranelift/codegen/src/machinst/buffer.rs | 16 ++++++++-------- cranelift/filetests/src/function_runner.rs | 3 ++- cranelift/filetests/src/test_interpret.rs | 3 ++- .../peepmatic/crates/runtime/src/optimizer.rs | 2 +- crates/runtime/src/externref.rs | 2 +- crates/wiggle/src/lib.rs | 2 +- crates/wiggle/wasmtime/macro/src/lib.rs | 2 +- 11 files changed, 23 insertions(+), 19 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 074de2b47a..4c8193198d 100644 --- a/.github/workflows/main.yml +++ b/.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: diff --git a/cranelift/codegen/src/ir/extfunc.rs b/cranelift/codegen/src/ir/extfunc.rs index e2f2bb984b..9bb089fd56 100644 --- a/cranelift/codegen/src/ir/extfunc.rs +++ b/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, } diff --git a/cranelift/codegen/src/ir/globalvalue.rs b/cranelift/codegen/src/ir/globalvalue.rs index dae869445c..6c9b2d7bcf 100644 --- a/cranelift/codegen/src/ir/globalvalue.rs +++ b/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? diff --git a/cranelift/codegen/src/isa/aarch64/abi.rs b/cranelift/codegen/src/isa/aarch64/abi.rs index ed12ed0365..9a4f64896e 100644 --- a/cranelift/codegen/src/isa/aarch64/abi.rs +++ b/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 v1 in memory at [P+8]. -//! - Return v0 in memory at [P+16]. +//! - Return v2 in memory at `[P]`. +//! - Return v1 in memory at `[P+8]`. +//! - Return v0 in memory at `[P+16]`. use crate::ir; use crate::ir::types; diff --git a/cranelift/codegen/src/machinst/buffer.rs b/cranelift/codegen/src/machinst/buffer.rs index 4d9bc828f8..5f54b1ba77 100644 --- a/cranelift/codegen/src/machinst/buffer.rs +++ b/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 -//! allocator does not need to insert any spills/reloads/moves in edge blocks, -//! results in many suboptimal branch patterns. The lowering also pays no -//! attention to block order, and so two-target conditional forms (cond-br -//! followed by uncond-br) can often by avoided because one of the targets is -//! the fallthrough. There are several cases here where we can simplify to use -//! fewer branches. +//! [BlockLoweringOrder](super::BlockLoweringOrder), combined with many empty +//! edge blocks when the register allocator does not need to insert any +//! spills/reloads/moves in edge blocks, results in many suboptimal branch +//! patterns. The lowering also pays no attention to block order, and so +//! two-target conditional forms (cond-br followed by uncond-br) can often by +//! avoided because one of the targets is the fallthrough. There are several +//! 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 diff --git a/cranelift/filetests/src/function_runner.rs b/cranelift/filetests/src/function_runner.rs index 69ad26029b..d195697246 100644 --- a/cranelift/filetests/src/function_runner.rs +++ b/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) -> Self { let trampolines = HashMap::new(); Self { isa, trampolines } diff --git a/cranelift/filetests/src/test_interpret.rs b/cranelift/filetests/src/test_interpret.rs index ccde4a0084..1545022375 100644 --- a/cranelift/filetests/src/test_interpret.rs +++ b/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}; diff --git a/cranelift/peepmatic/crates/runtime/src/optimizer.rs b/cranelift/peepmatic/crates/runtime/src/optimizer.rs index 3830a248bf..589c3f7761 100644 --- a/cranelift/peepmatic/crates/runtime/src/optimizer.rs +++ b/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 diff --git a/crates/runtime/src/externref.rs b/crates/runtime/src/externref.rs index a7bf80b6b3..2272c3bcb8 100644 --- a/crates/runtime/src/externref.rs +++ b/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 | diff --git a/crates/wiggle/src/lib.rs b/crates/wiggle/src/lib.rs index e756dc8dbb..0defe927d6 100644 --- a/crates/wiggle/src/lib.rs +++ b/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`. diff --git a/crates/wiggle/wasmtime/macro/src/lib.rs b/crates/wiggle/wasmtime/macro/src/lib.rs index 2a60df1a8c..f56c65d35c 100644 --- a/crates/wiggle/wasmtime/macro/src/lib.rs +++ b/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