Fix doc warnings

Author: mamcx

crates/bench/src/bin/summarize.rs

@@ -1,5 +1,5 @@
 //! Script to pack benchmark results into JSON files.
-//! These are read by the benchmarks-viewer application: https://github.com/clockworklabs/benchmarks-viewer,
+//! These are read by the benchmarks-viewer application: <https://github.com/clockworklabs/benchmarks-viewer>,
 //! which is used to generate reports on the benchmarks.
 //! See also: the github actions scripts that invoke this command, `SpacetimeDB/.github/workflows/benchmarks.yml` and `SpacetimeDB/.github/workflows/callgrind_benchmarks.yml`.
 use clap::{Parser, Subcommand};
@@ -110,7 +110,7 @@ mod criterion {
     ///
     /// Unfortunately, there is no published library for this, so we use the schema
     /// from `critcmp` under the MIT license:
-    /// https://github.com/BurntSushi/critcmp/blob/daaf0383c3981c98a6eaaef47142755e5bddb3c4/src/data.rs
+    /// <https://github.com/BurntSushi/critcmp/blob/daaf0383c3981c98a6eaaef47142755e5bddb3c4/src/data.rs>
     ///
     /// TODO(jgilles): update this if we update our Criterion version past 0.4.
     #[allow(unused)]

crates/bindings-macro/src/lib.rs

@@ -112,11 +112,11 @@ pub fn reducer(args: StdTokenStream, item: StdTokenStream) -> StdTokenStream {
 }
 
 /// It turns out to be shockingly difficult to construct an [`Attribute`].
-/// That type is not [`Parse`], instead having two distinct methods
+/// That type is not [`syn::parse::Parse`], instead having two distinct methods
 /// for parsing "inner" vs "outer" attributes.
 ///
-/// We need this [`Attribute`] in [`table`] so that we can "pushnew" it
-/// onto the end of a list of attributes. See comments within [`table`].
+/// We need this [`Attribute`] in [`crate::table()`] so that we can "pushnew" it
+/// onto the end of a list of attributes. See comments within [`crate::table()`].
 fn derive_table_helper_attr() -> Attribute {
     let source = quote!(#[derive(spacetimedb::__TableHelper)]);
 

crates/cli/src/config.rs

@@ -28,14 +28,14 @@ pub struct ServerConfig {
 }
 
 impl ServerConfig {
-    /// Generate a new [`Table`] representing this [`ServerConfig`].
+    /// Generate a new [`toml_edit::Table`] representing this [`ServerConfig`].
     pub fn as_table(&self) -> toml_edit::Table {
         let mut table = toml_edit::Table::new();
         Self::update_table(&mut table, self);
         table
     }
 
-    /// Update an existing [`Table`] with the values of a [`ServerConfig`].
+    /// Update an existing [`toml_edit::Table`] with the values of a [`ServerConfig`].
     pub fn update_table(edit: &mut toml_edit::Table, from: &ServerConfig) {
         set_table_opt_value(edit, NICKNAME_KEY, from.nickname.as_deref());
         set_table_opt_value(edit, HOST_KEY, Some(&from.host));

crates/cli/src/subcommands/subscribe.rs

@@ -198,7 +198,7 @@ where
     ws.send(msg.into()).await
 }
 
-/// Await the initial [`ServerMessage::SubscriptionUpdate`].
+/// Await the initial [`ws::ServerMessage::TransactionUpdateLight`] `|` [`ws::ServerMessage::TransactionUpdate`].
 /// If `module_def` is `Some`, print a JSON representation to stdout.
 async fn await_initial_update<S>(ws: &mut S, module_def: Option<&RawModuleDefV9>) -> anyhow::Result<()>
 where
@@ -232,7 +232,7 @@ where
     Ok(())
 }
 
-/// Print `num` [`ServerMessage::TransactionUpdate`] messages as JSON.
+/// Print `num` [`ws::ServerMessage::TransactionUpdateLight`] `|` [`ws::ServerMessage::TransactionUpdate`] messages as JSON.
 /// If `num` is `None`, keep going indefinitely.
 async fn consume_transaction_updates<S>(
     ws: &mut S,

crates/client-api/src/auth.rs

@@ -65,7 +65,7 @@ impl SpacetimeCreds {
 
 /// The auth information in a request.
 ///
-/// This is inserted as an extension by [`auth_middleware`]; make sure that's applied if you're making expecting
+/// This is inserted as an extension by [`anon_auth_middleware`]; make sure that's applied if you're making expecting
 /// this to be present.
 #[derive(Clone)]
 pub struct SpacetimeAuth {

crates/client-api/src/lib.rs

@@ -130,7 +130,7 @@ impl Host {
 
 /// Parameters for publishing a database.
 ///
-/// See [`ControlStateDelegate::publish_database`].
+/// See [`ControlStateWriteAccess::publish_database`].
 pub struct DatabaseDef {
     /// The [`Identity`] the database shall have.
     pub database_identity: Identity,

crates/core/src/callgrind_flag.rs

@@ -13,10 +13,10 @@ use std::sync::atomic::{AtomicU32, Ordering};
 /// Our solution is to wrap the code of interest in a function that is only called when the global flag is set.
 ///
 /// See: documentation on valgrind/callgrind/iai-callgrind's `toggle-collect` option (ctrl-f on these pages):
-/// - https://github.com/iai-callgrind/iai-callgrind/
-/// - https://valgrind.org/docs/manual/cl-manual.html
+/// - <https://github.com/iai-callgrind/iai-callgrind/>
+/// - <https://valgrind.org/docs/manual/cl-manual.html>
 ///
-/// We do NOT use the valgrind macros (or the crate https://github.com/2dav/crabgrind) because they are a pain to build.
+/// We do NOT use the valgrind macros (or the crate <https://github.com/2dav/crabgrind>) because they are a pain to build.
 /// (Hours wasted here: 9.)
 /// Instead, we have a wrapper function which is only called when a global flag is set.
 ///

crates/core/src/client/client_connection.rs

@@ -41,8 +41,8 @@ pub struct ClientConfig {
     pub protocol: Protocol,
     /// The client's desired (conditional) compression algorithm, if any.
     pub compression: Compression,
-    /// Whether the client prefers full [`TransactionUpdate`]s
-    /// rather than  [`TransactionUpdateLight`]s on a successful update.
+    /// Whether the client prefers full [`spacetimedb_client_api_messages::websocket::TransactionUpdate`]s
+    /// rather than  [`spacetimedb_client_api_messages::websocket::TransactionUpdateLight`]s on a successful update.
     // TODO(centril): As more knobs are added, make this into a bitfield (when there's time).
     pub tx_update_full: bool,
 }

crates/core/src/db/datastore/locking_tx_datastore/committed_state.rs

@@ -432,7 +432,7 @@ impl CommittedState {
     }
 
     /// When there's an index on `cols`,
-    /// returns an iterator over the [TableIndex] that yields all the [`RowRef`]s
+    /// returns an iterator over the [spacetimedb_table::table_index::TableIndex] that yields all the [`RowRef`]s
     /// that match the specified `range` in the indexed column.
     ///
     /// Matching is defined by `Ord for AlgebraicValue`.

crates/core/src/db/datastore/locking_tx_datastore/datastore.rs

@@ -166,7 +166,7 @@ impl Locking {
     /// - Construct all the tables referenced by `snapshot`, computing their schemas
     ///   either from known system table schemas or from `st_table` and friends.
     /// - Populate those tables with all rows in `snapshot`.
-    /// - Construct a [`HashMapBlobStore`] containing all the large blobs referenced by `snapshot`,
+    /// - Construct a [`spacetimedb_table::blob_store::HashMapBlobStore`] containing all the large blobs referenced by `snapshot`,
     ///   with reference counts specified in `snapshot`.
     /// - Do [`CommittedState::reset_system_table_schemas`] to fix-up auto_inc IDs in the system tables,
     ///   to ensure those schemas match what [`Self::bootstrap`] would install.

crates/core/src/db/datastore/locking_tx_datastore/delete_table.rs

@@ -3,7 +3,7 @@ use spacetimedb_table::{
     indexes::{max_rows_in_page, PageIndex, PageOffset, RowPointer, Size, SquashedOffset},
 };
 
-/// A table recording which rows of a table in the [`CommittedState`] that have been deleted.
+/// A table recording which rows of a table in the [`super::committed_state::CommittedState`] that have been deleted.
 pub struct DeleteTable {
     /// Keeps track of all the deleted row pointers.
     deleted: Vec<Option<FixedBitSet>>,
@@ -27,7 +27,7 @@ impl DeleteTable {
         }
     }
 
-    /// Returns whether `ptr`, belonging to a table in [`CommittedState`], is recorded as deleted.
+    /// Returns whether `ptr`, belonging to a table in [`super::committed_state::CommittedState`], is recorded as deleted.
     pub fn contains(&self, ptr: RowPointer) -> bool {
         let page_idx = ptr.page_index().idx();
         match self.deleted.get(page_idx) {
@@ -36,7 +36,7 @@ impl DeleteTable {
         }
     }
 
-    /// Marks `ptr`, belonging to a table in [`CommittedState`], as deleted.
+    /// Marks `ptr`, belonging to a table in [`super::committed_state::CommittedState`], as deleted.
     ///
     /// Returns `true` if `ptr` was not previously marked.
     pub fn insert(&mut self, ptr: RowPointer) -> bool {
@@ -84,7 +84,7 @@ impl DeleteTable {
         }
     }
 
-    /// Un-marks `ptr`, belonging to a table in [`CommittedState`], as deleted.
+    /// Un-marks `ptr`, belonging to a table in [`super::committed_state::CommittedState`], as deleted.
     pub fn remove(&mut self, ptr: RowPointer) -> bool {
         let fixed_row_size = self.fixed_row_size;
         let page_idx = ptr.page_index().idx();

crates/core/src/db/datastore/system_tables.rs

@@ -8,7 +8,7 @@
 //!     - You will probably need to add a new ID type in `spacetimedb_primitives`,
 //!       with trait implementations in `spacetimedb_sats::{typespace, de::impl, ser::impl}`.
 //! - Add it to [`system_tables`], and define a constant for its index there.
-//! - Use [`st_fields_enum`] to define its column enum.
+//! - Use `st_fields_enum` to define its column enum.
 //! - Register its schema in [`system_module_def`], making sure to call `validate_system_table` at the end of the function.
 
 use crate::db::relational_db::RelationalDB;
@@ -216,7 +216,7 @@ st_fields_enum!(enum StIndexFields {
 });
 // WARNING: For a stable schema, don't change the field names and discriminants.
 st_fields_enum!(
-    /// The fields that define the internal table [crate::db::relational_db::ST_SEQUENCES_NAME].
+    /// The fields that define the internal table [ST_SEQUENCE_NAME].
     enum StSequenceFields {
     "sequence_id", SequenceId = 0,
     "sequence_name", SequenceName = 1,
@@ -859,13 +859,13 @@ impl From<Identity> for IdentityViaU256 {
 /// * `database_identity` is the [`Identity`] of the database.
 /// * `owner_identity` is the [`Identity`] of the owner of the database.
 /// * `program_kind` is the [`ModuleKind`] (currently always [`WASM_MODULE`]).
-/// * `program_hash` is the [`Hash`] of the raw bytes of the (compiled) module.
+/// * `program_hash` is the [`struct@Hash`] of the raw bytes of the (compiled) module.
 /// * `program_bytes` are the raw bytes of the (compiled) module.
 /// * `module_version` is the version of the module.
 ///
 /// | identity | owner_identity |  program_kind | program_bytes | program_hash        | module_version |
 /// |------------------|----------------|---------------|---------------|---------------------|----------------|
-/// | <bytes>          | <bytes>        |  0            | <bytes>       | <bytes>             | <string>       |
+/// | `<bytes>`        | `<bytes>`      |  0            | `<bytes>`     | `<bytes>`           | `<string>`     |
 #[derive(Clone, Debug, Eq, PartialEq, SpacetimeType)]
 #[sats(crate = spacetimedb_lib)]
 pub struct StModuleRow {
@@ -898,9 +898,9 @@ pub fn read_identity_from_col(row: RowRef<'_>, col: impl StFields) -> Result<Ide
     Ok(Identity::from_u256(row.read_col(col.col_id())?))
 }
 
-/// Read a [`Hash`] directly from the column `col` in `row`.
+/// Read a [`struct@Hash`] directly from the column `col` in `row`.
 ///
-/// The [`Hash`] is assumed to be stored as a flat byte array.
+/// The [`struct@Hash`] is assumed to be stored as a flat byte array.
 pub fn read_hash_from_col(row: RowRef<'_>, col: impl StFields) -> Result<Hash, DBError> {
     Ok(Hash::from_u256(row.read_col(col.col_id())?))
 }

crates/core/src/db/datastore/traits.rs

@@ -41,7 +41,7 @@ use spacetimedb_table::table::RowRef;
 /// nuanced example of how postgres deals with consistency guarantees at lower
 /// isolation levels.
 ///
-/// - https://stackoverflow.com/questions/55254236/do-i-need-higher-transaction-isolation-to-make-constraints-work-reliably-in-post
+/// - <https://stackoverflow.com/questions/55254236/do-i-need-higher-transaction-isolation-to-make-constraints-work-reliably-in-post>
 ///
 /// Thus from an application perspective, isolation anomalies may cause the data
 /// to be inconsistent or incorrect but will **not** cause it to violate the
@@ -79,13 +79,13 @@ use spacetimedb_table::table::RowRef;
 /// However since then database researchers have identified and cataloged many
 /// more. See:
 ///
-/// - https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/tr-95-51.pdf
-/// - https://pmg.csail.mit.edu/papers/adya-phd.pdf
+/// - <https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/tr-95-51.pdf>
+/// - <https://pmg.csail.mit.edu/papers/adya-phd.pdf>
 ///
 /// See the following table of anomalies for a more complete list used as a
 /// reference for database implementers:
 ///
-/// - https://github.com/ept/hermitage?tab=readme-ov-file#summary-of-test-results
+/// - <https://github.com/ept/hermitage?tab=readme-ov-file#summary-of-test-results>
 ///
 /// The following anomalies are not part of the SQL standard, but are important:
 ///
@@ -101,7 +101,7 @@ use spacetimedb_table::table::RowRef;
 /// PostgreSQL's documentation provides a good summary of the anomalies and
 /// isolation levels that it supports:
 ///
-/// - https://www.postgresql.org/docs/current/transaction-iso.html
+/// - <https://www.postgresql.org/docs/current/transaction-iso.html>
 ///
 /// IMPORTANT!!! The order of these isolation levels in the enum is significant
 /// because we often must check if one isolation level is higher (offers more

crates/core/src/db/relational_db.rs

@@ -223,7 +223,7 @@ impl RelationalDB {
     ///
     /// If, however, a non-empty `history` was supplied, [`Metadata`] will
     /// already be be set. In this case, i.e. if either [`Self::metadata`] or
-    /// [`Self::program_bytes`] return a `Some` value, [`Self::set_initialized`]
+    /// [`StModuleRow::program_bytes`] return a `Some` value, [`Self::set_initialized`]
     /// should _not_ be called.
     ///
     /// Sometimes, one may want to obtain a database without a module (e.g. for
@@ -652,7 +652,7 @@ impl RelationalDB {
     /// If `(tx_data, ctx)` should be appended to the commitlog, do so.
     ///
     /// Note that by this stage,
-    /// [`crate::db::datastore::locking_tx_datastore::committed_state::tx_consumes_offset`]
+    /// [`CommittedState::tx_consumes_offset`]
     /// has already decided based on the reducer and operations whether the transaction should be appended;
     /// this method is responsible only for reading its decision out of the `tx_data`
     /// and calling `durability.append_tx`.
@@ -1012,14 +1012,14 @@ impl RelationalDB {
         self.inner.constraint_id_from_name(tx, constraint_name)
     }
 
-    /// Adds the index into the [ST_INDEXES_NAME] table
+    /// Adds the index into the [super::datastore::system_tables::ST_INDEX_NAME] table
     ///
     /// NOTE: It loads the data from the table into it before returning
     pub fn create_index(&self, tx: &mut MutTx, schema: IndexSchema, is_unique: bool) -> Result<IndexId, DBError> {
         self.inner.create_index_mut_tx(tx, schema, is_unique)
     }
 
-    /// Removes the [`TableIndex`] from the database by their `index_id`
+    /// Removes the [`super::datastore::system_tables::StIndexRow`] from the database by their `index_id`
     pub fn drop_index(&self, tx: &mut MutTx, index_id: IndexId) -> Result<(), DBError> {
         self.inner.drop_index_mut_tx(tx, index_id)
     }
@@ -1167,7 +1167,7 @@ impl RelationalDB {
         self.inner.create_sequence_mut_tx(tx, sequence_schema)
     }
 
-    ///Removes the [Sequence] from database instance
+    ///Removes the [`super::datastore::system_tables::StSequenceRow`] from database instance
     pub fn drop_sequence(&self, tx: &mut MutTx, seq_id: SequenceId) -> Result<(), DBError> {
         self.inner.drop_sequence_mut_tx(tx, seq_id)
     }
@@ -1401,7 +1401,7 @@ pub mod tests_utils {
         /// Create a [`TestDB`] which stores data in a local commitlog,
         /// initialized with pre-existing data from `history`.
         ///
-        /// [`TestHistory::from_txes`] is an easy-ish way to construct a non-empty [`History`].
+        /// [`TestHistory::from_txes`] is an easy-ish way to construct a non-empty [`durability::History`].
         ///
         /// `expected_num_clients` is the expected size of the `connected_clients` return
         /// from [`RelationalDB::open`] after replaying `history`.

crates/core/src/host/host_controller.rs

@@ -669,7 +669,7 @@ struct Host {
     replica_ctx: Arc<ReplicaContext>,
     /// Scheduler for repeating reducers, operating on the current `module`.
     scheduler: Scheduler,
-    /// Handle to the metrics collection task started via [`disk_monitor`].
+    /// Handle to the metrics collection task started via [`storage_monitor`].
     ///
     /// The task collects metrics from the `replica_ctx`, and so stays alive as long
     /// as the `replica_ctx` is live. The task is aborted when [`Host`] is dropped.

crates/core/src/host/wasm_common/instrumentation.rs

@@ -14,7 +14,7 @@
 //! `noop` does nothing.
 //! `op` uses `std::time::Instant` and `std::time::Duration` to capture timings.
 //! Components which use the time-span interface will conditionally import one of the two modules, like:
-//! ```no-run
+//! ```no_run
 //! #[cfg(feature = "spacetimedb-wasm-instance-times)]
 //! use instrumentation::op as span;
 //! #[cfg(not(feature = "spacetimedb-wasm-instance-times)]

crates/core/src/host/wasmtime/wasm_instance_env.rs

@@ -251,7 +251,7 @@ impl WasmInstanceEnv {
     /// host call, to provide consistent error handling and instrumentation.
     ///
     /// This method should be used as opposed to a manual implementation,
-    /// as it helps with upholding the safety invariants of [`bindings_sys::call`].
+    /// as it helps with upholding the safety invariants of `spacetimedb_bindings_sys::call`.
     ///
     /// Returns an error if writing `T` to `out` errors.
     fn cvt_ret<O: WasmPointee>(
@@ -379,7 +379,7 @@ impl WasmInstanceEnv {
     /// Starts iteration on each row, as BSATN-encoded, of a table identified by `table_id`.
     ///
     /// On success, the iterator handle is written to the `out` pointer.
-    /// This handle can be advanced by [`row_iter_bsatn_advance`].
+    /// This handle can be advanced by [`Self::row_iter_bsatn_advance`].
     ///
     /// # Traps
     ///
@@ -436,7 +436,7 @@ impl WasmInstanceEnv {
     /// which is unique for the module.
     ///
     /// On success, the iterator handle is written to the `out` pointer.
-    /// This handle can be advanced by [`row_iter_bsatn_advance`].
+    /// This handle can be advanced by [`Self::row_iter_bsatn_advance`].
     ///
     /// # Non-obvious queries
     ///
@@ -783,7 +783,7 @@ impl WasmInstanceEnv {
     /// in WASM memory.
     ///
     /// This syscall will delete all the rows found by
-    /// [`datastore_index_scan_range_bsatn`] with the same arguments passed,
+    /// [`Self::datastore_index_scan_range_bsatn`] with the same arguments passed,
     /// including `prefix_elems`.
     /// See `datastore_index_scan_range_bsatn` for details.
     ///
@@ -1089,7 +1089,7 @@ impl WasmInstanceEnv {
     }
 
     /// Logs at `level` a `message` message occuring in `filename:line_number`
-    /// with [`target`](target) being the module path at the `log!` invocation site.
+    /// with [`target`](https://docs.rs/log/latest/log/struct.Record.html#method.target) being the module path at the `log!` invocation site.
     ///
     /// These various pointers are interpreted lossily as UTF-8 strings with a corresponding `_len`.
     ///
@@ -1107,8 +1107,6 @@ impl WasmInstanceEnv {
     /// - `target` is not NULL and `target_ptr[..target_len]` is not in bounds of WASM memory.
     /// - `filename` is not NULL and `filename_ptr[..filename_len]` is not in bounds of WASM memory.
     /// - `message` is not NULL and `message_ptr[..message_len]` is not in bounds of WASM memory.
-    ///
-    /// [target]: https://docs.rs/log/latest/log/struct.Record.html#method.target
     #[tracing::instrument(level = "trace", skip_all)]
     pub fn console_log(
         caller: Caller<'_, Self>,
@@ -1154,7 +1152,7 @@ impl WasmInstanceEnv {
 
     /// Begins a timing span with `name = name_ptr[..name_len]`.
     ///
-    /// When the returned `ConsoleTimerId` is passed to [`console_timer_end`],
+    /// When the returned `ConsoleTimerId` is passed to [`Self::console_timer_end`],
     /// the duration between the calls will be printed to the module's logs.
     ///
     /// The `name` is interpreted lossily as a UTF-8 string.