Adds a CI action that tries to build the documentation (#68)

## What Changed?

Adds a CI job which builds the documentation for the user-facing crates
(`paralegal-spdg` and `paralegal-policy`) with all warnings as errors
`-Drustdoc::all`.

Just running these commands uncovered a bunch of errors in the docs,
which this PR fixes also.

## Why Does It Need To?

This will let us ensure at the PR level that any changes do not lead to
for instance dead links in the documentation, at least for those crates
that are somewhat external.

## Checklist

- [x] Above description has been filled out so that upon quash merge we
have a
  good record of what changed.
- [x] New functions, methods, types are documented. Old documentation is
updated
  if necessary
- [x] Documentation in Notion has been updated
- [x] Tests for new behaviors are provided
  - [x] New test suites (if any) ave been added to the CI tests (in
`.github/workflows/rust.yml`) either as compiler test or integration
test.
*Or* justification for their omission from CI has been provided in this
PR
    description.

.github/workflows/rust.yml

@@ -126,3 +126,28 @@ jobs:
     - name: Complaints about properties
       run: cargo clippy --all -- -D warnings
       working-directory: props
+
+  documentation:
+    name: Documentation Test
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Cache Toolchain
+      uses: actions/cache@v3
+      with:
+        path: ~/.rustup
+        key: ${{ runner.os }}-rust-toolchain-${{ hashFiles('rust-toolchain.toml') }}
+    - name: Cache Dependencies
+      uses: actions/cache@v3
+      with:
+        path: |
+          ~/.cargo/bin/
+          ~/.cargo/registry/index/
+          ~/.cargo/registry/cache/
+          ~/.cargo/git/db/
+          target/
+        key: ${{ runner.os }}-rust-deps-${{ hashFiles('Cargo.lock', 'rust-toolchain.toml') }}
+    - name: Here come the complaints
+      run: |
+        cargo rustdoc -p paralegal-spdg -- -Drustdoc::all
+        cargo rustdoc -p paralegal-policy -- -Drustdoc::all

crates/paralegal-policy/src/context.rs

@@ -339,7 +339,7 @@ impl Context {
 /// struct is at least one (e.g. [`Self::holds`] is sound).
 ///
 /// The stable API of this struct is [`Self::holds`], [`Self::assert_holds`] and
-/// [`Self::found_any`]. Otherwise the information in this struct and its
+/// [`Self::is_vacuous`]. Otherwise the information in this struct and its
 /// printed representations should be considered unstable and
 /// for-human-eyes-only.
 pub struct AlwaysHappensBefore {

crates/paralegal-spdg/src/global_location.rs

@@ -42,13 +42,13 @@
 //! [`GlobalLocation::single`] is used to construct global locations that are
 //! not nested in a call chain (such as the location of `let x = 1` within
 //! `bar`). A nested location (such as nesting this one behind the call to `bar`
-//! in `foo`) is done using [`GlobalLocation::relativize`].
+//! in `foo`) is done using [`GlobalLocationS::relativize`].
 //!
 //! In the example we would first construct global locations for all locations
 //! in `bar` with (pseudocode) `bar_bb0[0] = `[`GlobalLocation::single(bb0[0],
 //! bar_id)`](GlobalLocation::single) and then make the relative locations to
-//! foo with [`bar_bb0[0].relativize(bb0[0], foo_id)`](GlobalLocation::relativize) and
-//! [`bar_bb0[0].relativize(bb1[0], foo_id)`](GlobalLocation::relativize) for the first and second
+//! foo with [`bar_bb0[0].relativize(bb0[0], foo_id)`](GlobalLocationS::relativize) and
+//! [`bar_bb0[0].relativize(bb1[0], foo_id)`](GlobalLocationS::relativize) for the first and second
 //! inlining respectively.
 //!
 //! # Representation
@@ -69,9 +69,6 @@ use std::{cmp::Ordering, fmt, ops::Deref};
 
 use crate::rustc_portable::*;
 
-/// The payload type of a global location.
-///
-/// You will probably want to operate on the interned wrapper type [`GlobalLocation`].
 #[derive(PartialEq, Eq, Hash, Debug, Clone, Copy, Serialize, Deserialize)]
 pub struct GlobalLocationS {
     #[cfg_attr(feature = "rustc", serde(with = "rustc_proxies::DefId"))]
@@ -201,7 +198,7 @@ impl fmt::Display for RawGlobalLocation {
 /// information on usage and rational.
 ///
 /// To construct these values use [`GlobalLocation::single`] and
-/// [`GlobalLocation::relativize`].
+/// [`GlobalLocationS::relativize`].
 ///
 /// INVARIANT: `self.0.len() > 0`
 #[derive(PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Copy, Serialize, Deserialize)]

crates/paralegal-spdg/src/lib.rs

@@ -47,7 +47,7 @@ pub type TypeDescriptor = DefId;
 pub type Function = Identifier;
 
 /// Name of the file used for emitting the JSON serialized
-/// [`ProgramDescription`](crate::desc::ProgramDescription).
+/// [`ProgramDescription`](crate::ProgramDescription).
 pub const FLOW_GRAPH_OUT_NAME: &str = "flow-graph.json";
 
 /// Types of annotations we support.

crates/paralegal-spdg/src/rustc_proxies.rs

@@ -75,7 +75,7 @@ proxy_index! {
     /// Proxy for `def_id::DefIndex`
     DefIndex("def_id::DefIndex") from "def_index_as_u32";
 
-    /// Proxy for [`hir::def_id::CrateNum`]
+    /// Proxy for `hir::def_id::CrateNum`
     CrateNum("hir::def_id::CrateNum") from "crate_num_as_u32"
 }
 
@@ -109,7 +109,7 @@ proxy_struct! {
     }
 
     #[derive(Ord, PartialOrd)]
-    /// Proxy for [`def_id::DefId`]
+    /// Proxy for `def_id::DefId`
     DefId("def_id::DefId") {
         index: def_id::DefIndex => DefIndex, "DefIndex",
         krate: hir::def_id::CrateNum => CrateNum, "CrateNum"

crates/paralegal-spdg/src/utils.rs

@@ -29,11 +29,10 @@ pub mod serde_map_via_vec {
     //! The JSON serializer for [`HashMap`] needs the keys to serialize to a
     //! JSON string object, but sometimes that is not the case. Since the
     //! [`HashMap`] struct only requires its keys be [`Eq`] and [`Hash`] other
-    //! non-string values may have been used as key (such is the case in
-    //! [`Bodies`](super::Bodies)). Unfortunately you can still use the
-    //! [`Serialize`] trait on [`HashMap`], even if the keys do not serialize to
-    //! strings. Instead a runtime error will be thrown when a non-string key is
-    //! encountered.
+    //! non-string values may have been used as key. Unfortunately you can still
+    //! use the [`Serialize`] trait on [`HashMap`], even if the keys do not
+    //! serialize to strings. Instead a runtime error will be thrown when a
+    //! non-string key is encountered.
     //!
     //! This module converts the [`HashMap`] into a [`Vec`] of tuples and
     //! (de)serializes that, which permits arbitrary types to be used for the