doc: Minor rust docs fixes (#3312)

SrGesus · web-flow · commit eaad7b2c9a0a · 2024-07-20T12:59:52.000-07:00
* Fixed some rust docs intra-doc non functioning links

* Minor tweaks

* Added warning for MSSQL not being functional yet

* Fixed requested changes

* Readded missing time

* Aligned table
diff --git a/sqlx-core/src/any/connection/backend.rs b/sqlx-core/src/any/connection/backend.rs
@@ -26,8 +26,6 @@ pub trait AnyConnectionBackend: std::any::Any + Debug + Send + 'static {
     fn ping(&mut self) -> BoxFuture<'_, crate::Result<()>>;
 
     /// Begin a new transaction or establish a savepoint within the active transaction.
-    ///
-    /// Returns a [`Transaction`] for controlling and tracking the new transaction.
     fn begin(&mut self) -> BoxFuture<'_, crate::Result<()>>;
 
     fn commit(&mut self) -> BoxFuture<'_, crate::Result<()>>;
diff --git a/sqlx-core/src/any/mod.rs b/sqlx-core/src/any/mod.rs
@@ -1,7 +1,7 @@
 //! **SEE DOCUMENTATION BEFORE USE**. Generic database driver with the specific driver selected at runtime.
 //!
 //! The underlying database drivers are chosen at runtime from the list set via
-//! [`install_drivers`][self::driver::install_drivers). Any use of `AnyConnection` or `AnyPool`
+//! [`install_drivers`][self::driver::install_drivers]. Any use of `AnyConnection` or `AnyPool`
 //! without this will panic.
 use crate::executor::Executor;
 
diff --git a/sqlx-core/src/database.rs b/sqlx-core/src/database.rs
@@ -10,7 +10,7 @@
 //! | Database | Version | Driver |
 //! | - | - | - |
 //! | [MariaDB] | 10.1+ | [`mysql`] |
-//! | [Microsoft SQL Server] | 2019 | [`mssql`] |
+//! | [Microsoft SQL Server] | 2019 | [`mssql`] (Pending a full rewrite) |
 //! | [MySQL] | 5.6, 5.7, 8.0 | [`mysql`] |
 //! | [PostgreSQL] | 9.5+ | [`postgres`] |
 //! | [SQLite] | 3.20.1+ | [`sqlite`] |
diff --git a/sqlx-core/src/executor.rs b/sqlx-core/src/executor.rs
@@ -22,10 +22,10 @@ use std::fmt::Debug;
 ///  * [`&Pool`](super::pool::Pool)
 ///  * [`&mut Connection`](super::connection::Connection)
 ///
-/// The [`Executor`](crate::Executor) impls for [`Transaction`](crate::Transaction)
+/// The [`Executor`] impls for [`Transaction`](crate::transaction::Transaction)
 /// and [`PoolConnection`](crate::pool::PoolConnection) have been deleted because they
 /// cannot exist in the new crate architecture without rewriting the Executor trait entirely.
-/// To fix this breakage, simply add a dereference where an impl [`Executor`](crate::Executor) is expected, as
+/// To fix this breakage, simply add a dereference where an impl [`Executor`] is expected, as
 /// they both dereference to the inner connection type which will still implement it:
 /// * `&mut transaction` -> `&mut *transaction`
 /// * `&mut connection` -> `&mut *connection`
diff --git a/sqlx-core/src/from_row.rs b/sqlx-core/src/from_row.rs
@@ -173,7 +173,7 @@ use crate::{error::Error, row::Row};
 ///    .fetch_one(&mut some_connection)
 ///    .await?;
 ///
-/// `Default` for `Vec<Address>` is an empty vector.
+/// // `Default` for `Vec<Address>` is an empty vector.
 /// assert!(user.addresses.is_empty());
 /// ```
 ///
diff --git a/sqlx-core/src/pool/mod.rs b/sqlx-core/src/pool/mod.rs
@@ -11,7 +11,7 @@
 //! SQLx provides a canonical connection pool implementation intended to satisfy the majority
 //! of use cases.
 //!
-//! See [Pool][crate::pool::Pool] for details.
+//! See [Pool] for details.
 //!
 //! Type aliases are provided for each database to make it easier to sprinkle `Pool` through
 //! your codebase:
@@ -110,7 +110,7 @@ pub use self::maybe::MaybePoolConnection;
 /// when at this limit and all connections are checked out, the task will be made to wait until
 /// a connection becomes available.
 ///
-/// You can configure the connection limit, and other parameters, using [PoolOptions][crate::pool::PoolOptions].
+/// You can configure the connection limit, and other parameters, using [PoolOptions].
 ///
 /// Calls to `acquire()` are fair, i.e. fulfilled on a first-come, first-serve basis.
 ///
@@ -310,7 +310,7 @@ impl<DB: Database> Pool<DB> {
     ///
     /// The pool will establish connections only as needed.
     ///
-    /// Refer to the relevant [`ConnectOptions`] impl for your database for the expected URL format:
+    /// Refer to the relevant [`ConnectOptions`][crate::connection::ConnectOptions] impl for your database for the expected URL format:
     ///
     /// * Postgres: [`PgConnectOptions`][crate::postgres::PgConnectOptions]
     /// * MySQL: [`MySqlConnectOptions`][crate::mysql::MySqlConnectOptions]
@@ -502,12 +502,6 @@ impl<DB: Database> Pool<DB> {
     }
 
     /// Returns the number of connections active and idle (not in use).
-    ///
-    /// As of 0.6.0, this has been fixed to use a separate atomic counter and so should be fine to
-    /// call even at high load.
-    ///
-    /// This previously called [`crossbeam::queue::ArrayQueue::len()`] which waits for the head and
-    /// tail pointers to be in a consistent state, which may never happen at high levels of churn.
     pub fn num_idle(&self) -> usize {
         self.0.num_idle()
     }
diff --git a/sqlx-mysql/src/options/mod.rs b/sqlx-mysql/src/options/mod.rs
@@ -349,7 +349,7 @@ impl MySqlConnectOptions {
     /// By default, this is `true` (`NO_ENGINE_SUBSTITUTION` is passed, forbidding engine
     /// substitution).
     ///
-    /// https://mariadb.com/kb/en/sql-mode/
+    /// <https://mariadb.com/kb/en/sql-mode/>
     pub fn no_engine_subsitution(mut self, flag_val: bool) -> Self {
         self.no_engine_subsitution = flag_val;
         self
diff --git a/sqlx-mysql/src/types/mod.rs b/sqlx-mysql/src/types/mod.rs
@@ -21,7 +21,7 @@
 //! | `Ipv4Addr`                            | INET4 (MariaDB-only), VARCHAR, TEXT                  |
 //! | `Ipv6Addr`                            | INET6 (MariaDB-only), VARCHAR, TEXT                  |
 //! | [`MySqlTime`]                         | TIME (encode and decode full range)                  |
-//! | [`Duration`]                          | TIME (for decoding positive values only)             |
+//! | [`Duration`][std::time::Duration]     | TIME (for decoding positive values only)             |
 //!
 //! ##### Note: `BOOLEAN`/`BOOL` Type
 //! MySQL and MariaDB treat `BOOLEAN` as an alias of the `TINYINT` type:
diff --git a/sqlx-mysql/src/types/mysql_time.rs b/sqlx-mysql/src/types/mysql_time.rs
@@ -18,7 +18,7 @@ use std::time::Duration;
 /// Allowed range is `-838:59:59.0` to `838:59:59.0`.
 ///
 /// If this value is used for a time-of-day, the range should be `00:00:00.0` to `23:59:59.999999`.
-/// You can use [`Self::is_time_of_day()`] to check this easily.
+/// You can use [`Self::is_valid_time_of_day()`] to check this easily.
 ///
 /// * [MySQL Manual 13.2.3: The TIME Type](https://dev.mysql.com/doc/refman/8.3/en/time.html)
 /// * [MariaDB Manual: TIME](https://mariadb.com/kb/en/time/)
@@ -125,7 +125,7 @@ impl MySqlTime {
     /// Construct a [`MySqlTime`] that is valid for use as a `TIME` value.
     ///
     /// ### Errors
-    /// * [`MySqlTimeError::NegativeZero`] if all fields are 0 but `sign` is [`MySqlSign::Negative`].
+    /// * [`MySqlTimeError::NegativeZero`] if all fields are 0 but `sign` is [`MySqlTimeSign::Negative`].
     /// * [`MySqlTimeError::FieldRange`] if any field is out of range:
     ///     * `hours > 838`
     ///     * `minutes > 59`
diff --git a/sqlx-postgres/src/advisory_lock.rs b/sqlx-postgres/src/advisory_lock.rs
@@ -46,12 +46,12 @@ pub struct PgAdvisoryLock {
 /// 64-bit integer, and one keyed by a pair of two 32-bit integers. The Postgres docs
 /// specify that these key spaces "do not overlap":
 ///
-/// https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS
+/// <https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS>
 ///
 /// The documentation for the `pg_locks` system view explains further how advisory locks
 /// are treated in Postgres:
 ///
-/// https://www.postgresql.org/docs/current/view-pg-locks.html
+/// <https://www.postgresql.org/docs/current/view-pg-locks.html>
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[non_exhaustive]
 pub enum PgAdvisoryLockKey {
diff --git a/sqlx-postgres/src/copy.rs b/sqlx-postgres/src/copy.rs
@@ -24,7 +24,7 @@ impl PgConnection {
     /// returned.
     ///
     /// Command examples and accepted formats for `COPY` data are shown here:
-    /// https://www.postgresql.org/docs/current/sql-copy.html
+    /// <https://www.postgresql.org/docs/current/sql-copy.html>
     ///
     /// ### Note
     /// [PgCopyIn::finish] or [PgCopyIn::abort] *must* be called when finished or the connection
@@ -51,7 +51,7 @@ impl PgConnection {
     /// need to read and discard all the remaining queued data, which could take some time.
     ///
     /// Command examples and accepted formats for `COPY` data are shown here:
-    /// https://www.postgresql.org/docs/current/sql-copy.html
+    /// <https://www.postgresql.org/docs/current/sql-copy.html>
     #[allow(clippy::needless_lifetimes)]
     pub async fn copy_out_raw<'c>(
         &'c mut self,
@@ -61,7 +61,7 @@ impl PgConnection {
     }
 }
 
-/// Implements methods for directly executing `COPY FROM/TO STDOUT` on a [`PgPool`].
+/// Implements methods for directly executing `COPY FROM/TO STDOUT` on a [`PgPool`][crate::PgPool].
 ///
 /// This is a replacement for the inherent methods on `PgPool` which could not exist
 /// once the Postgres driver was moved out into its own crate.
@@ -76,7 +76,7 @@ pub trait PgPoolCopyExt {
     /// returned.
     ///
     /// Command examples and accepted formats for `COPY` data are shown here:
-    /// https://www.postgresql.org/docs/current/sql-copy.html
+    /// <https://www.postgresql.org/docs/current/sql-copy.html>
     ///
     /// ### Note
     /// [PgCopyIn::finish] or [PgCopyIn::abort] *must* be called when finished or the connection
@@ -104,7 +104,7 @@ pub trait PgPoolCopyExt {
     /// need to read and discard all the remaining queued data, which could take some time.
     ///
     /// Command examples and accepted formats for `COPY` data are shown here:
-    /// https://www.postgresql.org/docs/current/sql-copy.html
+    /// <https://www.postgresql.org/docs/current/sql-copy.html>
     fn copy_out_raw<'a>(
         &'a self,
         statement: &'a str,
diff --git a/sqlx-postgres/src/types/lquery.rs b/sqlx-postgres/src/types/lquery.rs
@@ -30,13 +30,13 @@ pub enum PgLQueryParseError {
 
 /// Container for a Label Tree Query (`lquery`) in Postgres.
 ///
-/// See https://www.postgresql.org/docs/current/ltree.html
+/// See <https://www.postgresql.org/docs/current/ltree.html>
 ///
 /// ### Note: Requires Postgres 13+
 ///
 /// This integration requires that the `lquery` type support the binary format in the Postgres
 /// wire protocol, which only became available in Postgres 13.
-/// ([Postgres 13.0 Release Notes, Additional Modules][https://www.postgresql.org/docs/13/release-13.html#id-1.11.6.11.5.14])
+/// ([Postgres 13.0 Release Notes, Additional Modules](https://www.postgresql.org/docs/13/release-13.html#id-1.11.6.11.5.14))
 ///
 /// Ideally, SQLx's Postgres driver should support falling back to text format for types
 /// which don't have `typsend` and `typrecv` entries in `pg_type`, but that work still needs
diff --git a/sqlx-postgres/src/types/ltree.rs b/sqlx-postgres/src/types/ltree.rs
@@ -66,13 +66,13 @@ impl Display for PgLTreeLabel {
 
 /// Container for a Label Tree (`ltree`) in Postgres.
 ///
-/// See https://www.postgresql.org/docs/current/ltree.html
+/// See <https://www.postgresql.org/docs/current/ltree.html>
 ///
 /// ### Note: Requires Postgres 13+
 ///
 /// This integration requires that the `ltree` type support the binary format in the Postgres
 /// wire protocol, which only became available in Postgres 13.
-/// ([Postgres 13.0 Release Notes, Additional Modules][https://www.postgresql.org/docs/13/release-13.html#id-1.11.6.11.5.14])
+/// ([Postgres 13.0 Release Notes, Additional Modules](https://www.postgresql.org/docs/13/release-13.html#id-1.11.6.11.5.14))
 ///
 /// Ideally, SQLx's Postgres driver should support falling back to text format for types
 /// which don't have `typsend` and `typrecv` entries in `pg_type`, but that work still needs
@@ -95,7 +95,7 @@ impl PgLTree {
         Self::default()
     }
 
-    /// creates ltree from a [Vec<PgLTreeLabel>]
+    /// creates ltree from a [`Vec<PgLTreeLabel>`]
     pub fn from(labels: Vec<PgLTreeLabel>) -> Self {
         Self { labels }
     }
diff --git a/sqlx-postgres/src/types/money.rs b/sqlx-postgres/src/types/money.rs
@@ -32,7 +32,7 @@ use std::{
 /// If you're not sure what locale your database is set to or how many decimal digits it specifies,
 /// you can execute `SHOW lc_monetary;` to get the locale name, and then look it up in this list
 /// (you can ignore the `.utf8` prefix):
-/// https://lh.2xlibre.net/values/frac_digits/
+/// <https://lh.2xlibre.net/values/frac_digits/>
 ///
 /// If that link is dead and you're on a POSIX-compliant system (Unix, FreeBSD) you can also execute:
 ///
@@ -45,7 +45,7 @@ use std::{
 ///
 /// Note that if `frac_digits` for the locale is outside the range `[0, 10]`, Postgres assumes
 /// it's a sentinel value and defaults to 2:
-/// https://github.com/postgres/postgres/blob/master/src/backend/utils/adt/cash.c#L114-L123
+/// <https://github.com/postgres/postgres/blob/master/src/backend/utils/adt/cash.c#L114-L123>
 ///
 /// [`MONEY`]: https://www.postgresql.org/docs/current/datatype-money.html
 #[derive(Debug, PartialEq, Eq, Clone, Copy, Default)]
@@ -68,7 +68,7 @@ impl PgMoney {
     ///
     /// See the type-level docs for an explanation of `locale_frac_digits`.
     ///
-    /// [`BigDecimal`]: crate::types::BigDecimal
+    /// [`BigDecimal`]: bigdecimal::BigDecimal
     #[cfg(feature = "bigdecimal")]
     pub fn to_bigdecimal(self, locale_frac_digits: i64) -> bigdecimal::BigDecimal {
         let digits = num_bigint::BigInt::from(self.0);
@@ -80,7 +80,7 @@ impl PgMoney {
     ///
     /// See the type-level docs for an explanation of `locale_frac_digits`.
     ///
-    /// [`Decimal`]: crate::types::Decimal
+    /// [`Decimal`]: rust_decimal::Decimal
     #[cfg(feature = "rust_decimal")]
     pub fn to_decimal(self, locale_frac_digits: u32) -> rust_decimal::Decimal {
         rust_decimal::Decimal::new(self.0, locale_frac_digits)
@@ -93,7 +93,7 @@ impl PgMoney {
     /// Note that `Decimal` has 96 bits of precision, but `PgMoney` only has 63 plus the sign bit.
     /// If the value is larger than 63 bits it will be truncated.
     ///
-    /// [`Decimal`]: crate::types::Decimal
+    /// [`Decimal`]: rust_decimal::Decimal
     #[cfg(feature = "rust_decimal")]
     pub fn from_decimal(mut decimal: rust_decimal::Decimal, locale_frac_digits: u32) -> Self {
         // this is all we need to convert to our expected locale's `frac_digits`
@@ -116,7 +116,7 @@ impl PgMoney {
         Self(if is_negative { -value } else { value })
     }
 
-    /// Convert a [`BigDecimal`](crate::types::BigDecimal) value into money using the correct precision
+    /// Convert a [`BigDecimal`](bigdecimal::BigDecimal) value into money using the correct precision
     /// defined in the PostgreSQL settings. The default precision is two.
     #[cfg(feature = "bigdecimal")]
     pub fn from_bigdecimal(
diff --git a/sqlx-sqlite/src/options/mod.rs b/sqlx-sqlite/src/options/mod.rs
@@ -66,7 +66,7 @@ pub struct SqliteConnectOptions {
     pub(crate) vfs: Option<Cow<'static, str>>,
 
     pub(crate) pragmas: IndexMap<Cow<'static, str>, Option<Cow<'static, str>>>,
-    /// Extensions are specified as a pair of <Extension Name : Optional Entry Point>, the majority
+    /// Extensions are specified as a pair of \<Extension Name : Optional Entry Point>, the majority
     /// of SQLite extensions will use the default entry points specified in the docs, these should
     /// be added to the map with a `None` value.
     /// <https://www.sqlite.org/loadext.html#loading_an_extension>
@@ -212,7 +212,7 @@ impl SqliteConnectOptions {
     /// Sets the name of the database file.
     ///
     /// This is a low-level API, and SQLx will apply no special treatment for `":memory:"` as an
-    /// in-memory database using this method. Using [SqliteConnectOptions::from_str] may be
+    /// in-memory database using this method. Using [`SqliteConnectOptions::from_str()`][SqliteConnectOptions#from_str] may be
     /// preferred for simple use cases.
     pub fn filename(mut self, filename: impl AsRef<Path>) -> Self {
         self.filename = Cow::Owned(filename.as_ref().to_owned());
