From eaad7b2c9a0ac171327be0aebb5b4249c5685de3 Mon Sep 17 00:00:00 2001 From: SrGesus <108523575+SrGesus@users.noreply.github.com> Date: Sat, 20 Jul 2024 20:59:52 +0100 Subject: [PATCH] doc: Minor rust docs fixes (#3312) * 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 --- sqlx-core/src/any/connection/backend.rs | 2 -- sqlx-core/src/any/mod.rs | 2 +- sqlx-core/src/database.rs | 2 +- sqlx-core/src/executor.rs | 4 ++-- sqlx-core/src/from_row.rs | 2 +- sqlx-core/src/pool/mod.rs | 12 +++--------- sqlx-mysql/src/options/mod.rs | 2 +- sqlx-mysql/src/types/mod.rs | 2 +- sqlx-mysql/src/types/mysql_time.rs | 4 ++-- sqlx-postgres/src/advisory_lock.rs | 4 ++-- sqlx-postgres/src/copy.rs | 10 +++++----- sqlx-postgres/src/types/lquery.rs | 4 ++-- sqlx-postgres/src/types/ltree.rs | 6 +++--- sqlx-postgres/src/types/money.rs | 12 ++++++------ sqlx-sqlite/src/options/mod.rs | 4 ++-- 15 files changed, 32 insertions(+), 40 deletions(-) diff --git a/sqlx-core/src/any/connection/backend.rs b/sqlx-core/src/any/connection/backend.rs index 7f051bd41..b30cbe83f 100644 --- 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 index 2398aa0ac..695de331f 100644 --- 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 index d17621c71..e44c3d88a 100644 --- 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 index 4a33931da..84b1a660d 100644 --- 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 index a6129b961..9c647d370 100644 --- 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
` is an empty vector. +/// // `Default` for `Vec
` 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 index 5424705cb..ca593bbb7 100644 --- 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 Pool { /// /// 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 Pool { } /// 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 index 535362a3f..dd2214f76 100644 --- 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/ + /// 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 index 8408a78ba..d71d441e6 100644 --- 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 index d71985c82..1e91b82e0 100644 --- 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 index 928524ede..82191726f 100644 --- 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 +/// /// /// 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 +/// #[derive(Debug, Clone, PartialEq, Eq)] #[non_exhaustive] pub enum PgAdvisoryLockKey { diff --git a/sqlx-postgres/src/copy.rs b/sqlx-postgres/src/copy.rs index 26e02e3b6..b33315cfa 100644 --- 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 + /// /// /// ### 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 + /// #[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 + /// /// /// ### 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 + /// 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 index f03958668..faed95751 100644 --- 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 /// /// ### 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 index 9931ea4c7..531f50656 100644 --- 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 /// /// ### 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] + /// creates ltree from a [`Vec`] pub fn from(labels: Vec) -> Self { Self { labels } } diff --git a/sqlx-postgres/src/types/money.rs b/sqlx-postgres/src/types/money.rs index 45f4bdd83..52fc68795 100644 --- 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/ +/// /// /// 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 +/// /// /// [`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 index d3ed8b9f3..94e37815e 100644 --- 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>, pub(crate) pragmas: IndexMap, Option>>, - /// Extensions are specified as a pair of , the majority + /// Extensions are specified as a pair of \, 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. /// @@ -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) -> Self { self.filename = Cow::Owned(filename.as_ref().to_owned());