From 0312937d6a75b45d7e603fa8c6b083bc7774270b Mon Sep 17 00:00:00 2001 From: gwenn Date: Sun, 13 Jun 2021 09:17:35 +0200 Subject: [PATCH] Use #[doc(cfg)] Fix #835 --- Cargo.toml | 1 + libsqlite3-sys/build.rs | 5 ++++- src/backup.rs | 12 +++++------ src/blob/mod.rs | 8 +++---- src/collation.rs | 8 +++---- src/column.rs | 1 + src/error.rs | 7 ++++++ src/functions.rs | 18 +++++++++------- src/hooks.rs | 25 ++++++++++----------- src/lib.rs | 20 ++++++++++++++--- src/limits.rs | 6 +++--- src/load_extension_guard.rs | 3 ++- src/session.rs | 26 +++++++++++----------- src/statement.rs | 1 + src/trace.rs | 10 ++++----- src/types/from_sql.rs | 8 +++++-- src/types/mod.rs | 4 ++++ src/types/to_sql.rs | 8 ++++++- src/types/value.rs | 2 ++ src/vtab/array.rs | 4 ++-- src/vtab/csvtab.rs | 4 ++-- src/vtab/mod.rs | 43 +++++++++++++++++++++---------------- src/vtab/series.rs | 4 ++-- 23 files changed, 141 insertions(+), 87 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 8653da6..1933fc6 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -150,6 +150,7 @@ features = [ "array", "backup", "blob", "chrono", "collation", "functions", "lim all-features = false no-default-features = true default-target = "x86_64-unknown-linux-gnu" +rustdoc-args = ["--cfg", "docsrs"] [package.metadata.playground] features = ["bundled-full"] diff --git a/libsqlite3-sys/build.rs b/libsqlite3-sys/build.rs index c151a37..fc3ac15 100644 --- a/libsqlite3-sys/build.rs +++ b/libsqlite3-sys/build.rs @@ -181,7 +181,10 @@ mod build_bundled { if cfg!(feature = "bundled-sqlcipher-vendored-openssl") { cfg.include(std::env::var("DEP_OPENSSL_INCLUDE").unwrap()); - println!("cargo:rustc-link-lib=static=crypto"); // cargo will resolve downstream to the static lib in openssl-sys + println!("cargo:rustc-link-lib=static=crypto"); // cargo will + // resolve downstream + // to the static + // lib in openssl-sys } else if is_windows { // FIXME README says that bundled-sqlcipher is Unix only, and the sources are // configured on a Unix machine. So maybe this should be made unreachable. diff --git a/src/backup.rs b/src/backup.rs index 6cb586b..88677fe 100644 --- a/src/backup.rs +++ b/src/backup.rs @@ -1,4 +1,4 @@ -//! `feature = "backup"` Online SQLite backup API. +//! Online SQLite backup API. //! //! To create a [`Backup`], you must have two distinct [`Connection`]s - one //! for the source (which can be used while the backup is running) and one for @@ -44,7 +44,7 @@ use crate::error::{error_from_handle, error_from_sqlite_code}; use crate::{Connection, DatabaseName, Result}; impl Connection { - /// `feature = "backup"` Back up the `name` database to the given + /// Back up the `name` database to the given /// destination path. /// /// If `progress` is not `None`, it will be called periodically @@ -84,7 +84,7 @@ impl Connection { } } - /// `feature = "backup"` Restore the given source path into the + /// Restore the given source path into the /// `name` database. If `progress` is not `None`, it will be /// called periodically until the restore completes. /// @@ -131,7 +131,7 @@ impl Connection { } } -/// `feature = "backup"` Possible successful results of calling +/// Possible successful results of calling /// [`Backup::step`]. #[derive(Copy, Clone, Debug, PartialEq, Eq)] #[non_exhaustive] @@ -152,7 +152,7 @@ pub enum StepResult { Locked, } -/// `feature = "backup"` Struct specifying the progress of a backup. The +/// Struct specifying the progress of a backup. The /// percentage completion can be calculated as `(pagecount - remaining) / /// pagecount`. The progress of a backup is as of the last call to /// [`step`](Backup::step) - if the source database is modified after a call to @@ -166,7 +166,7 @@ pub struct Progress { pub pagecount: c_int, } -/// `feature = "backup"` A handle to an online backup. +/// A handle to an online backup. pub struct Backup<'a, 'b> { phantom_from: PhantomData<&'a Connection>, phantom_to: PhantomData<&'b Connection>, diff --git a/src/blob/mod.rs b/src/blob/mod.rs index cd9ad31..7b89647 100644 --- a/src/blob/mod.rs +++ b/src/blob/mod.rs @@ -1,4 +1,4 @@ -//! `feature = "blob"` Incremental BLOB I/O. +//! Incremental BLOB I/O. //! //! Note that SQLite does not provide API-level access to change the size of a //! BLOB; that must be performed through SQL statements. @@ -196,7 +196,7 @@ use crate::{Connection, DatabaseName, Result}; mod pos_io; -/// `feature = "blob"` Handle to an open BLOB. See +/// Handle to an open BLOB. See /// [`rusqlite::blob`](crate::blob) documentation for in-depth discussion. pub struct Blob<'conn> { conn: &'conn Connection, @@ -206,7 +206,7 @@ pub struct Blob<'conn> { } impl Connection { - /// `feature = "blob"` Open a handle to the BLOB located in `row_id`, + /// Open a handle to the BLOB located in `row_id`, /// `column`, `table` in database `db`. /// /// # Failure @@ -400,7 +400,7 @@ impl Drop for Blob<'_> { } } -/// `feature = "blob"` BLOB of length N that is filled with zeroes. +/// BLOB of length N that is filled with zeroes. /// /// Zeroblobs are intended to serve as placeholders for BLOBs whose content is /// later written using incremental BLOB I/O routines. diff --git a/src/collation.rs b/src/collation.rs index 2b93a9a..7e6673a 100644 --- a/src/collation.rs +++ b/src/collation.rs @@ -1,4 +1,4 @@ -//! `feature = "collation"` Add, remove, or modify a collation +//! Add, remove, or modify a collation use std::cmp::Ordering; use std::os::raw::{c_char, c_int, c_void}; use std::panic::{catch_unwind, UnwindSafe}; @@ -14,7 +14,7 @@ unsafe extern "C" fn free_boxed_value(p: *mut c_void) { } impl Connection { - /// `feature = "collation"` Add or modify a collation. + /// Add or modify a collation. #[inline] pub fn create_collation<'c, C>(&'c self, collation_name: &str, x_compare: C) -> Result<()> where @@ -25,7 +25,7 @@ impl Connection { .create_collation(collation_name, x_compare) } - /// `feature = "collation"` Collation needed callback + /// Collation needed callback #[inline] pub fn collation_needed( &self, @@ -34,7 +34,7 @@ impl Connection { self.db.borrow_mut().collation_needed(x_coll_needed) } - /// `feature = "collation"` Remove collation. + /// Remove collation. #[inline] pub fn remove_collation(&self, collation_name: &str) -> Result<()> { self.db.borrow_mut().remove_collation(collation_name) diff --git a/src/column.rs b/src/column.rs index ae965a6..ac7c4a2 100644 --- a/src/column.rs +++ b/src/column.rs @@ -132,6 +132,7 @@ impl Statement<'_> { /// sure that current statement has already been stepped once before /// calling this method. #[cfg(feature = "column_decltype")] + #[cfg_attr(docsrs, doc(cfg(feature = "column_decltype")))] pub fn columns(&self) -> Vec { let n = self.column_count(); let mut cols = Vec::with_capacity(n as usize); diff --git a/src/error.rs b/src/error.rs index a8d3f23..68e87b0 100644 --- a/src/error.rs +++ b/src/error.rs @@ -72,15 +72,18 @@ pub enum Error { /// [`functions::Context::get`](crate::functions::Context::get) when the /// function argument cannot be converted to the requested type. #[cfg(feature = "functions")] + #[cfg_attr(docsrs, doc(cfg(feature = "functions")))] InvalidFunctionParameterType(usize, Type), /// Error returned by [`vtab::Values::get`](crate::vtab::Values::get) when /// the filter argument cannot be converted to the requested type. #[cfg(feature = "vtab")] + #[cfg_attr(docsrs, doc(cfg(feature = "vtab")))] InvalidFilterParameterType(usize, Type), /// An error case available for implementors of custom user functions (e.g., /// [`create_scalar_function`](crate::Connection::create_scalar_function)). #[cfg(feature = "functions")] + #[cfg_attr(docsrs, doc(cfg(feature = "functions")))] #[allow(dead_code)] UserFunctionError(Box), @@ -94,11 +97,13 @@ pub enum Error { /// An error case available for implementors of custom modules (e.g., /// [`create_module`](crate::Connection::create_module)). #[cfg(feature = "vtab")] + #[cfg_attr(docsrs, doc(cfg(feature = "vtab")))] #[allow(dead_code)] ModuleError(String), /// An unwinding panic occurs in an UDF (user-defined function). #[cfg(feature = "functions")] + #[cfg_attr(docsrs, doc(cfg(feature = "functions")))] UnwindingPanic, /// An error returned when @@ -106,6 +111,7 @@ pub enum Error { /// retrieve data of a different type than what had been stored using /// [`Context::set_aux`](crate::functions::Context::set_aux). #[cfg(feature = "functions")] + #[cfg_attr(docsrs, doc(cfg(feature = "functions")))] GetAuxWrongType, /// Error when the SQL contains multiple statements. @@ -120,6 +126,7 @@ pub enum Error { /// [`Blob::raw_read_at_exact`](crate::blob::Blob::raw_read_at_exact) will /// return it if the blob has insufficient data. #[cfg(feature = "blob")] + #[cfg_attr(docsrs, doc(cfg(feature = "blob")))] BlobSizeError, } diff --git a/src/functions.rs b/src/functions.rs index b021000..f5e051d 100644 --- a/src/functions.rs +++ b/src/functions.rs @@ -1,4 +1,4 @@ -//! `feature = "functions"` Create or redefine SQL functions. +//! Create or redefine SQL functions. //! //! # Example //! @@ -104,7 +104,7 @@ unsafe extern "C" fn free_boxed_value(p: *mut c_void) { drop(Box::from_raw(p as *mut T)); } -/// `feature = "functions"` Context is a wrapper for the SQLite function +/// Context is a wrapper for the SQLite function /// evaluation context. pub struct Context<'a> { ctx: *mut sqlite3_context, @@ -260,7 +260,7 @@ impl Deref for ConnectionRef<'_> { type AuxInner = Arc; -/// `feature = "functions"` Aggregate is the callback interface for user-defined +/// Aggregate is the callback interface for user-defined /// aggregate function. /// /// `A` is the type of the aggregation context and `T` is the type of the final @@ -292,9 +292,10 @@ where fn finalize(&self, _: &mut Context<'_>, _: Option) -> Result; } -/// `feature = "window"` WindowAggregate is the callback interface for +/// WindowAggregate is the callback interface for /// user-defined aggregate window function. #[cfg(feature = "window")] +#[cfg_attr(docsrs, doc(cfg(feature = "window")))] pub trait WindowAggregate: Aggregate where A: RefUnwindSafe + UnwindSafe, @@ -341,7 +342,7 @@ impl Default for FunctionFlags { } impl Connection { - /// `feature = "functions"` Attach a user-defined scalar function to + /// Attach a user-defined scalar function to /// this database connection. /// /// `fn_name` is the name the function will be accessible from SQL. @@ -395,7 +396,7 @@ impl Connection { .create_scalar_function(fn_name, n_arg, flags, x_func) } - /// `feature = "functions"` Attach a user-defined aggregate function to this + /// Attach a user-defined aggregate function to this /// database connection. /// /// # Failure @@ -419,12 +420,13 @@ impl Connection { .create_aggregate_function(fn_name, n_arg, flags, aggr) } - /// `feature = "window"` Attach a user-defined aggregate window function to + /// Attach a user-defined aggregate window function to /// this database connection. /// /// See `https://sqlite.org/windowfunctions.html#udfwinfunc` for more /// information. #[cfg(feature = "window")] + #[cfg_attr(docsrs, doc(cfg(feature = "window")))] #[inline] pub fn create_window_function( &self, @@ -443,7 +445,7 @@ impl Connection { .create_window_function(fn_name, n_arg, flags, aggr) } - /// `feature = "functions"` Removes a user-defined function from this + /// Removes a user-defined function from this /// database connection. /// /// `fn_name` and `n_arg` should match the name and number of arguments diff --git a/src/hooks.rs b/src/hooks.rs index e7d2670..943e1ea 100644 --- a/src/hooks.rs +++ b/src/hooks.rs @@ -1,4 +1,4 @@ -//! `feature = "hooks"` Commit, Data Change and Rollback Notification Callbacks +//! Commit, Data Change and Rollback Notification Callbacks #![allow(non_camel_case_types)] use std::os::raw::{c_char, c_int, c_void}; @@ -9,11 +9,12 @@ use crate::ffi; use crate::{Connection, InnerConnection}; -/// `feature = "hooks"` Action Codes +/// Action Codes #[derive(Clone, Copy, Debug, PartialEq)] #[repr(i32)] #[non_exhaustive] #[allow(clippy::upper_case_acronyms)] +#[cfg_attr(docsrs, doc(cfg(feature = "hooks")))] pub enum Action { /// Unsupported / unexpected action UNKNOWN = -1, @@ -37,7 +38,7 @@ impl From for Action { } } -/// `feature = "hooks"` The context recieved by an authorizer hook. +/// The context recieved by an authorizer hook. /// /// See for more info. #[derive(Clone, Copy, Debug, PartialEq)] @@ -53,7 +54,7 @@ pub struct AuthContext<'c> { pub accessor: Option<&'c str>, } -/// `feature = "hooks"` Actions and arguments found within a statement during +/// Actions and arguments found within a statement during /// preparation. /// /// See for more info. @@ -254,7 +255,7 @@ impl<'c> AuthAction<'c> { table_name, column_name, }, - (ffi::SQLITE_SELECT, _, _) => Self::Select, + (ffi::SQLITE_SELECT, ..) => Self::Select, (ffi::SQLITE_TRANSACTION, Some(operation_str), _) => Self::Transaction { operation: TransactionOperation::from_str(operation_str), }, @@ -286,7 +287,7 @@ impl<'c> AuthAction<'c> { savepoint_name, }, #[cfg(feature = "modern_sqlite")] - (ffi::SQLITE_RECURSIVE, _, _) => Self::Recursive, + (ffi::SQLITE_RECURSIVE, ..) => Self::Recursive, (code, arg1, arg2) => Self::Unknown { code, arg1, arg2 }, } } @@ -295,7 +296,7 @@ impl<'c> AuthAction<'c> { pub(crate) type BoxedAuthorizer = Box FnMut(AuthContext<'c>) -> Authorization + Send + 'static>; -/// `feature = "hooks"` A transaction operation. +/// A transaction operation. #[derive(Clone, Copy, Debug, PartialEq)] #[non_exhaustive] pub enum TransactionOperation { @@ -338,7 +339,7 @@ impl Authorization { } impl Connection { - /// `feature = "hooks"` Register a callback function to be invoked whenever + /// Register a callback function to be invoked whenever /// a transaction is committed. /// /// The callback returns `true` to rollback. @@ -350,7 +351,7 @@ impl Connection { self.db.borrow_mut().commit_hook(hook); } - /// `feature = "hooks"` Register a callback function to be invoked whenever + /// Register a callback function to be invoked whenever /// a transaction is committed. /// /// The callback returns `true` to rollback. @@ -362,7 +363,7 @@ impl Connection { self.db.borrow_mut().rollback_hook(hook); } - /// `feature = "hooks"` Register a callback function to be invoked whenever + /// Register a callback function to be invoked whenever /// a row is updated, inserted or deleted in a rowid table. /// /// The callback parameters are: @@ -380,7 +381,7 @@ impl Connection { self.db.borrow_mut().update_hook(hook); } - /// `feature = "hooks"` Register a query progress callback. + /// Register a query progress callback. /// /// The parameter `num_ops` is the approximate number of virtual machine /// instructions that are evaluated between successive invocations of the @@ -395,7 +396,7 @@ impl Connection { self.db.borrow_mut().progress_handler(num_ops, handler); } - /// `feature = "hooks"` Register an authorizer callback that's invoked + /// Register an authorizer callback that's invoked /// as a statement is being prepared. #[inline] pub fn authorizer<'c, F>(&self, hook: Option) diff --git a/src/lib.rs b/src/lib.rs index d16ffa8..18e2723 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -48,6 +48,7 @@ //! } //! ``` #![warn(missing_docs)] +#![cfg_attr(docsrs, feature(doc_cfg))] pub use libsqlite3_sys as ffi; @@ -88,23 +89,29 @@ pub use crate::version::*; mod error; #[cfg(feature = "backup")] +#[cfg_attr(docsrs, doc(cfg(feature = "backup")))] pub mod backup; #[cfg(feature = "blob")] +#[cfg_attr(docsrs, doc(cfg(feature = "blob")))] pub mod blob; mod busy; mod cache; #[cfg(feature = "collation")] +#[cfg_attr(docsrs, doc(cfg(feature = "collation")))] mod collation; mod column; pub mod config; #[cfg(any(feature = "functions", feature = "vtab"))] mod context; #[cfg(feature = "functions")] +#[cfg_attr(docsrs, doc(cfg(feature = "functions")))] pub mod functions; #[cfg(feature = "hooks")] +#[cfg_attr(docsrs, doc(cfg(feature = "hooks")))] mod hooks; mod inner_connection; #[cfg(feature = "limits")] +#[cfg_attr(docsrs, doc(cfg(feature = "limits")))] pub mod limits; #[cfg(feature = "load_extension")] mod load_extension_guard; @@ -113,15 +120,18 @@ mod pragma; mod raw_statement; mod row; #[cfg(feature = "session")] +#[cfg_attr(docsrs, doc(cfg(feature = "session")))] pub mod session; mod statement; #[cfg(feature = "trace")] +#[cfg_attr(docsrs, doc(cfg(feature = "trace")))] pub mod trace; mod transaction; pub mod types; mod unlock_notify; mod version; #[cfg(feature = "vtab")] +#[cfg_attr(docsrs, doc(cfg(feature = "vtab")))] pub mod vtab; pub(crate) mod util; @@ -714,7 +724,7 @@ impl Connection { r.map_err(move |err| (self, err)) } - /// `feature = "load_extension"` Enable loading of SQLite extensions. + /// Enable loading of SQLite extensions. /// Strongly consider using `LoadExtensionGuard` instead of this function. /// /// ## Example @@ -733,12 +743,13 @@ impl Connection { /// /// Will return `Err` if the underlying SQLite call fails. #[cfg(feature = "load_extension")] + #[cfg_attr(docsrs, doc(cfg(feature = "load_extension")))] #[inline] pub fn load_extension_enable(&self) -> Result<()> { self.db.borrow_mut().enable_load_extension(1) } - /// `feature = "load_extension"` Disable loading of SQLite extensions. + /// Disable loading of SQLite extensions. /// /// See `load_extension_enable` for an example. /// @@ -746,12 +757,13 @@ impl Connection { /// /// Will return `Err` if the underlying SQLite call fails. #[cfg(feature = "load_extension")] + #[cfg_attr(docsrs, doc(cfg(feature = "load_extension")))] #[inline] pub fn load_extension_disable(&self) -> Result<()> { self.db.borrow_mut().enable_load_extension(0) } - /// `feature = "load_extension"` Load the SQLite extension at `dylib_path`. + /// Load the SQLite extension at `dylib_path`. /// `dylib_path` is passed through to `sqlite3_load_extension`, which may /// attempt OS-specific modifications if the file cannot be loaded directly. /// @@ -775,6 +787,7 @@ impl Connection { /// /// Will return `Err` if the underlying SQLite call fails. #[cfg(feature = "load_extension")] + #[cfg_attr(docsrs, doc(cfg(feature = "load_extension")))] #[inline] pub fn load_extension>( &self, @@ -853,6 +866,7 @@ impl Connection { /// Determine if all associated prepared statements have been reset. #[inline] #[cfg(feature = "modern_sqlite")] // 3.8.6 + #[cfg_attr(docsrs, doc(cfg(feature = "modern_sqlite")))] pub fn is_busy(&self) -> bool { self.db.borrow().is_busy() } diff --git a/src/limits.rs b/src/limits.rs index cacaa90..76aafd3 100644 --- a/src/limits.rs +++ b/src/limits.rs @@ -1,4 +1,4 @@ -//! `feature = "limits"` Run-Time Limits +//! Run-Time Limits use std::os::raw::c_int; @@ -8,14 +8,14 @@ pub use crate::ffi::Limit; use crate::Connection; impl Connection { - /// `feature = "limits"` Returns the current value of a limit. + /// Returns the current value of a limit. #[inline] pub fn limit(&self, limit: Limit) -> i32 { let c = self.db.borrow(); unsafe { ffi::sqlite3_limit(c.db(), limit as c_int, -1) } } - /// `feature = "limits"` Changes the limit to `new_val`, returning the prior + /// Changes the limit to `new_val`, returning the prior /// value of the limit. #[inline] pub fn set_limit(&self, limit: Limit, new_val: i32) -> i32 { diff --git a/src/load_extension_guard.rs b/src/load_extension_guard.rs index b4c38c2..aae0034 100644 --- a/src/load_extension_guard.rs +++ b/src/load_extension_guard.rs @@ -1,6 +1,6 @@ use crate::{Connection, Result}; -/// `feature = "load_extension"` RAII guard temporarily enabling SQLite +/// RAII guard temporarily enabling SQLite /// extensions to be loaded. /// /// ## Example @@ -14,6 +14,7 @@ use crate::{Connection, Result}; /// conn.load_extension(Path::new("my_sqlite_extension"), None) /// } /// ``` +#[cfg_attr(docsrs, doc(cfg(feature = "load_extension")))] pub struct LoadExtensionGuard<'conn> { conn: &'conn Connection, } diff --git a/src/session.rs b/src/session.rs index b40e4b0..0789e9b 100644 --- a/src/session.rs +++ b/src/session.rs @@ -1,4 +1,4 @@ -//! `feature = "session"` [Session Extension](https://sqlite.org/sessionintro.html) +//! [Session Extension](https://sqlite.org/sessionintro.html) #![allow(non_camel_case_types)] use std::ffi::CStr; @@ -19,7 +19,7 @@ use crate::{errmsg_to_string, str_to_cstring, Connection, DatabaseName, Result}; // https://sqlite.org/session.html -/// `feature = "session"` An instance of this object is a session that can be +/// An instance of this object is a session that can be /// used to record changes to a database. pub struct Session<'conn> { phantom: PhantomData<&'conn Connection>, @@ -223,7 +223,7 @@ impl Drop for Session<'_> { } } -/// `feature = "session"` Invert a changeset +/// Invert a changeset #[inline] pub fn invert_strm(input: &mut dyn Read, output: &mut dyn Write) -> Result<()> { let input_ref = &input; @@ -239,7 +239,7 @@ pub fn invert_strm(input: &mut dyn Read, output: &mut dyn Write) -> Result<()> { Ok(()) } -/// `feature = "session"` Combine two changesets +/// Combine two changesets #[inline] pub fn concat_strm( input_a: &mut dyn Read, @@ -262,7 +262,7 @@ pub fn concat_strm( Ok(()) } -/// `feature = "session"` Changeset or Patchset +/// Changeset or Patchset pub struct Changeset { cs: *mut c_void, n: c_int, @@ -313,7 +313,7 @@ impl Drop for Changeset { } } -/// `feature = "session"` Cursor for iterating over the elements of a changeset +/// Cursor for iterating over the elements of a changeset /// or patchset. pub struct ChangesetIter<'changeset> { phantom: PhantomData<&'changeset Changeset>, @@ -367,7 +367,7 @@ impl FallibleStreamingIterator for ChangesetIter<'_> { } } -/// `feature = "session"` +/// Operation pub struct Operation<'item> { table_name: &'item str, number_of_columns: i32, @@ -410,7 +410,7 @@ impl Drop for ChangesetIter<'_> { } } -/// `feature = "session"` An item passed to a conflict-handler by +/// An item passed to a conflict-handler by /// [`Connection::apply`](crate::Connection::apply), or an item generated by /// [`ChangesetIter::next`](ChangesetIter::next). // TODO enum ? Delete, Insert, Update, ... @@ -517,7 +517,7 @@ impl ChangesetItem { } } -/// `feature = "session"` Used to combine two or more changesets or +/// Used to combine two or more changesets or /// patchsets pub struct Changegroup { cg: *mut ffi::sqlite3_changegroup, @@ -587,7 +587,7 @@ impl Drop for Changegroup { } impl Connection { - /// `feature = "session"` Apply a changeset to a database + /// Apply a changeset to a database pub fn apply(&self, cs: &Changeset, filter: Option, conflict: C) -> Result<()> where F: Fn(&str) -> bool + Send + RefUnwindSafe + 'static, @@ -621,7 +621,7 @@ impl Connection { Ok(()) } - /// `feature = "session"` Apply a changeset to a database + /// Apply a changeset to a database pub fn apply_strm( &self, input: &mut dyn Read, @@ -662,7 +662,7 @@ impl Connection { } } -/// `feature = "session"` Constants passed to the conflict handler +/// Constants passed to the conflict handler /// See [here](https://sqlite.org/session.html#SQLITE_CHANGESET_CONFLICT) for details. #[allow(missing_docs)] #[repr(i32)] @@ -690,7 +690,7 @@ impl From for ConflictType { } } -/// `feature = "session"` Constants returned by the conflict handler +/// Constants returned by the conflict handler /// See [here](https://sqlite.org/session.html#SQLITE_CHANGESET_ABORT) for details. #[allow(missing_docs)] #[repr(i32)] diff --git a/src/statement.rs b/src/statement.rs index 139f504..b4865f4 100644 --- a/src/statement.rs +++ b/src/statement.rs @@ -776,6 +776,7 @@ impl Statement<'_> { /// Returns a string containing the SQL text of prepared statement with /// bound parameters expanded. #[cfg(feature = "modern_sqlite")] + #[cfg_attr(docsrs, doc(cfg(feature = "modern_sqlite")))] pub fn expanded_sql(&self) -> Option { self.stmt .expanded_sql() diff --git a/src/trace.rs b/src/trace.rs index 8e8fd3a..1a16a2e 100644 --- a/src/trace.rs +++ b/src/trace.rs @@ -1,4 +1,4 @@ -//! `feature = "trace"` Tracing and profiling functions. Error and warning log. +//! Tracing and profiling functions. Error and warning log. use std::ffi::{CStr, CString}; use std::mem; @@ -11,7 +11,7 @@ use super::ffi; use crate::error::error_from_sqlite_code; use crate::{Connection, Result}; -/// `feature = "trace"` Set up the process-wide SQLite error logging callback. +/// Set up the process-wide SQLite error logging callback. /// /// # Safety /// @@ -53,7 +53,7 @@ pub unsafe fn config_log(callback: Option) -> Result<()> { } } -/// `feature = "trace"` Write a message into the error log established by +/// Write a message into the error log established by /// `config_log`. #[inline] pub fn log(err_code: c_int, msg: &str) { @@ -64,7 +64,7 @@ pub fn log(err_code: c_int, msg: &str) { } impl Connection { - /// `feature = "trace"` Register or clear a callback function that can be + /// Register or clear a callback function that can be /// used for tracing the execution of SQL statements. /// /// Prepared statement placeholders are replaced/logged with their assigned @@ -89,7 +89,7 @@ impl Connection { } } - /// `feature = "trace"` Register or clear a callback function that can be + /// Register or clear a callback function that can be /// used for profiling the execution of SQL statements. /// /// There can only be a single profiler defined for each database diff --git a/src/types/from_sql.rs b/src/types/from_sql.rs index 7381fdf..cefe2cb 100644 --- a/src/types/from_sql.rs +++ b/src/types/from_sql.rs @@ -15,15 +15,17 @@ pub enum FromSqlError { /// requested type. OutOfRange(i64), - /// `feature = "i128_blob"` Error returned when reading an `i128` from a + /// Error returned when reading an `i128` from a /// blob with a size other than 16. Only available when the `i128_blob` /// feature is enabled. #[cfg(feature = "i128_blob")] + #[cfg_attr(docsrs, doc(cfg(feature = "i128_blob")))] InvalidI128Size(usize), - /// `feature = "uuid"` Error returned when reading a `uuid` from a blob with + /// Error returned when reading a `uuid` from a blob with /// a size other than 16. Only available when the `uuid` feature is enabled. #[cfg(feature = "uuid")] + #[cfg_attr(docsrs, doc(cfg(feature = "uuid")))] InvalidUuidSize(usize), /// An error case available for implementors of the [`FromSql`] trait. @@ -176,6 +178,7 @@ impl FromSql for Vec { } #[cfg(feature = "i128_blob")] +#[cfg_attr(docsrs, doc(cfg(feature = "i128_blob")))] impl FromSql for i128 { #[inline] fn column_result(value: ValueRef<'_>) -> FromSqlResult { @@ -192,6 +195,7 @@ impl FromSql for i128 { } #[cfg(feature = "uuid")] +#[cfg_attr(docsrs, doc(cfg(feature = "uuid")))] impl FromSql for uuid::Uuid { #[inline] fn column_result(value: ValueRef<'_>) -> FromSqlResult { diff --git a/src/types/mod.rs b/src/types/mod.rs index 706be0c..60cdc24 100644 --- a/src/types/mod.rs +++ b/src/types/mod.rs @@ -75,14 +75,18 @@ pub use self::value_ref::ValueRef; use std::fmt; #[cfg(feature = "chrono")] +#[cfg_attr(docsrs, doc(cfg(feature = "chrono")))] mod chrono; mod from_sql; #[cfg(feature = "serde_json")] +#[cfg_attr(docsrs, doc(cfg(feature = "serde_json")))] mod serde_json; #[cfg(feature = "time")] +#[cfg_attr(docsrs, doc(cfg(feature = "time")))] mod time; mod to_sql; #[cfg(feature = "url")] +#[cfg_attr(docsrs, doc(cfg(feature = "url")))] mod url; mod value; mod value_ref; diff --git a/src/types/to_sql.rs b/src/types/to_sql.rs index 1bf7711..d6d987c 100644 --- a/src/types/to_sql.rs +++ b/src/types/to_sql.rs @@ -16,13 +16,15 @@ pub enum ToSqlOutput<'a> { /// An owned SQLite-representable value. Owned(Value), - /// `feature = "blob"` A BLOB of the given length that is filled with + /// A BLOB of the given length that is filled with /// zeroes. #[cfg(feature = "blob")] + #[cfg_attr(docsrs, doc(cfg(feature = "blob")))] ZeroBlob(i32), /// `feature = "array"` #[cfg(feature = "array")] + #[cfg_attr(docsrs, doc(cfg(feature = "array")))] Array(Array), } @@ -70,9 +72,11 @@ from_value!(Vec); // `i128` needs in `Into`, but it's probably fine for the moment, and not // worth adding another case to Value. #[cfg(feature = "i128_blob")] +#[cfg_attr(docsrs, doc(cfg(feature = "i128_blob")))] from_value!(i128); #[cfg(feature = "uuid")] +#[cfg_attr(docsrs, doc(cfg(feature = "uuid")))] from_value!(uuid::Uuid); impl ToSql for ToSqlOutput<'_> { @@ -162,9 +166,11 @@ to_sql_self!(f32); to_sql_self!(f64); #[cfg(feature = "i128_blob")] +#[cfg_attr(docsrs, doc(cfg(feature = "i128_blob")))] to_sql_self!(i128); #[cfg(feature = "uuid")] +#[cfg_attr(docsrs, doc(cfg(feature = "uuid")))] to_sql_self!(uuid::Uuid); macro_rules! to_sql_self_fallible( diff --git a/src/types/value.rs b/src/types/value.rs index 944655c..9d55809 100644 --- a/src/types/value.rs +++ b/src/types/value.rs @@ -41,6 +41,7 @@ impl From for Value { } #[cfg(feature = "i128_blob")] +#[cfg_attr(docsrs, doc(cfg(feature = "i128_blob")))] impl From for Value { #[inline] fn from(i: i128) -> Value { @@ -54,6 +55,7 @@ impl From for Value { } #[cfg(feature = "uuid")] +#[cfg_attr(docsrs, doc(cfg(feature = "uuid")))] impl From for Value { #[inline] fn from(id: uuid::Uuid) -> Value { diff --git a/src/vtab/array.rs b/src/vtab/array.rs index 713604c..2143ad4 100644 --- a/src/vtab/array.rs +++ b/src/vtab/array.rs @@ -1,4 +1,4 @@ -//! `feature = "array"` Array Virtual Table. +//! Array Virtual Table. //! //! Note: `rarray`, not `carray` is the name of the table valued function we //! define. @@ -57,7 +57,7 @@ impl ToSql for Array { } } -/// `feature = "array"` Register the "rarray" module. +/// Register the "rarray" module. pub fn load_module(conn: &Connection) -> Result<()> { let aux: Option<()> = None; conn.create_module("rarray", eponymous_only_module::(), aux) diff --git a/src/vtab/csvtab.rs b/src/vtab/csvtab.rs index 096f272..091102c 100644 --- a/src/vtab/csvtab.rs +++ b/src/vtab/csvtab.rs @@ -1,4 +1,4 @@ -//! `feature = "csvtab"` CSV Virtual Table. +//! CSV Virtual Table. //! //! Port of [csv](http://www.sqlite.org/cgi/src/finfo?name=ext/misc/csv.c) C //! extension: `https://www.sqlite.org/csv.html` @@ -35,7 +35,7 @@ use crate::vtab::{ }; use crate::{Connection, Error, Result}; -/// `feature = "csvtab"` Register the "csv" module. +/// Register the "csv" module. /// ```sql /// CREATE VIRTUAL TABLE vtab USING csv( /// filename=FILENAME -- Name of file containing CSV content diff --git a/src/vtab/mod.rs b/src/vtab/mod.rs index f364f1f..966c918 100644 --- a/src/vtab/mod.rs +++ b/src/vtab/mod.rs @@ -1,4 +1,4 @@ -//! `feature = "vtab"` Create virtual tables. +//! Create virtual tables. //! //! Follow these steps to create your own virtual table: //! 1. Write implementation of [`VTab`] and [`VTabCursor`] traits. @@ -57,7 +57,7 @@ use crate::{str_to_cstring, Connection, Error, InnerConnection, Result}; // ffi::sqlite3_vtab => VTab // ffi::sqlite3_vtab_cursor => VTabCursor -/// `feature = "vtab"` Virtual table module +/// Virtual table module /// /// (See [SQLite doc](https://sqlite.org/c3ref/module.html)) #[repr(transparent)] @@ -84,7 +84,7 @@ const ZERO_MODULE: ffi::sqlite3_module = unsafe { .module }; -/// `feature = "vtab"` Create a read-only virtual table implementation. +/// Create a read-only virtual table implementation. /// /// Step 2 of [Creating New Virtual Table Implementations](https://sqlite.org/vtab.html#creating_new_virtual_table_implementations). pub fn read_only_module<'vtab, T: CreateVTab<'vtab>>() -> &'static Module<'vtab, T> { @@ -122,7 +122,7 @@ pub fn read_only_module<'vtab, T: CreateVTab<'vtab>>() -> &'static Module<'vtab, } } -/// `feature = "vtab"` Create an eponymous only virtual table implementation. +/// Create an eponymous only virtual table implementation. /// /// Step 2 of [Creating New Virtual Table Implementations](https://sqlite.org/vtab.html#creating_new_virtual_table_implementations). pub fn eponymous_only_module<'vtab, T: VTab<'vtab>>() -> &'static Module<'vtab, T> { @@ -187,7 +187,7 @@ impl VTabConnection { } } -/// `feature = "vtab"` Virtual table instance trait. +/// Virtual table instance trait. /// /// # Safety /// @@ -228,7 +228,7 @@ pub unsafe trait VTab<'vtab>: Sized { fn open(&'vtab self) -> Result; } -/// `feature = "vtab"` Non-eponymous virtual table instance trait. +/// Non-eponymous virtual table instance trait. /// /// (See [SQLite doc](https://sqlite.org/c3ref/vtab.html)) pub trait CreateVTab<'vtab>: VTab<'vtab> { @@ -257,7 +257,7 @@ pub trait CreateVTab<'vtab>: VTab<'vtab> { } } -/// `feature = "vtab"` Index constraint operator. +/// Index constraint operator. /// See [Virtual Table Constraint Operator Codes](https://sqlite.org/c3ref/c_index_constraint_eq.html) for details. #[derive(Debug, PartialEq)] #[allow(non_snake_case, non_camel_case_types, missing_docs)] @@ -302,7 +302,7 @@ impl From for IndexConstraintOp { } } -/// `feature = "vtab"` Pass information into and receive the reply from the +/// Pass information into and receive the reply from the /// [`VTab::best_index`] method. /// /// (See [SQLite doc](http://sqlite.org/c3ref/index_info.html)) @@ -370,6 +370,7 @@ impl IndexInfo { /// Estimated number of rows returned. #[cfg(feature = "modern_sqlite")] // SQLite >= 3.8.2 + #[cfg_attr(docsrs, doc(cfg(feature = "modern_sqlite")))] #[inline] pub fn set_estimated_rows(&mut self, estimated_rows: i64) { unsafe { @@ -402,7 +403,7 @@ impl<'a> Iterator for IndexConstraintIter<'a> { } } -/// `feature = "vtab"` WHERE clause constraint. +/// WHERE clause constraint. pub struct IndexConstraint<'a>(&'a ffi::sqlite3_index_constraint); impl IndexConstraint<'_> { @@ -425,7 +426,7 @@ impl IndexConstraint<'_> { } } -/// `feature = "vtab"` Information about what parameters to pass to +/// Information about what parameters to pass to /// [`VTabCursor::filter`]. pub struct IndexConstraintUsage<'a>(&'a mut ffi::sqlite3_index_constraint_usage); @@ -463,7 +464,7 @@ impl<'a> Iterator for OrderByIter<'a> { } } -/// `feature = "vtab"` A column of the ORDER BY clause. +/// A column of the ORDER BY clause. pub struct OrderBy<'a>(&'a ffi::sqlite3_index_info_sqlite3_index_orderby); impl OrderBy<'_> { @@ -480,7 +481,7 @@ impl OrderBy<'_> { } } -/// `feature = "vtab"` Virtual table cursor trait. +/// Virtual table cursor trait. /// /// Implementations must be like: /// ```rust,ignore @@ -514,7 +515,7 @@ pub unsafe trait VTabCursor: Sized { fn rowid(&self) -> Result; } -/// `feature = "vtab"` Context is used by [`VTabCursor::column`] to specify the +/// Context is used by [`VTabCursor::column`] to specify the /// cell value. pub struct Context(*mut ffi::sqlite3_context); @@ -530,7 +531,7 @@ impl Context { // TODO sqlite3_vtab_nochange (http://sqlite.org/c3ref/vtab_nochange.html) } -/// `feature = "vtab"` Wrapper to [`VTabCursor::filter`] arguments, the values +/// Wrapper to [`VTabCursor::filter`] arguments, the values /// requested by [`VTab::best_index`]. pub struct Values<'a> { args: &'a [*mut ffi::sqlite3_value], @@ -560,10 +561,12 @@ impl Values<'_> { } FromSqlError::OutOfRange(i) => Error::IntegralValueOutOfRange(idx, i), #[cfg(feature = "i128_blob")] + #[cfg_attr(docsrs, doc(cfg(feature = "i128_blob")))] FromSqlError::InvalidI128Size(_) => { Error::InvalidColumnType(idx, idx.to_string(), value.data_type()) } #[cfg(feature = "uuid")] + #[cfg_attr(docsrs, doc(cfg(feature = "uuid")))] FromSqlError::InvalidUuidSize(_) => { Error::FromSqlConversionFailure(idx, value.data_type(), Box::new(err)) } @@ -573,6 +576,7 @@ impl Values<'_> { // `sqlite3_value_type` returns `SQLITE_NULL` for pointer. // So it seems not possible to enhance `ValueRef::from_value`. #[cfg(feature = "array")] + #[cfg_attr(docsrs, doc(cfg(feature = "array")))] fn get_array(&self, idx: usize) -> Option { use crate::types::Value; let arg = self.args[idx]; @@ -630,7 +634,7 @@ impl<'a> Iterator for ValueIter<'a> { } impl Connection { - /// `feature = "vtab"` Register a virtual table implementation. + /// Register a virtual table implementation. /// /// Step 3 of [Creating New Virtual Table /// Implementations](https://sqlite.org/vtab.html#creating_new_virtual_table_implementations). @@ -680,7 +684,7 @@ impl InnerConnection { } } -/// `feature = "vtab"` Escape double-quote (`"`) character occurrences by +/// Escape double-quote (`"`) character occurrences by /// doubling them (`""`). pub fn escape_double_quote(identifier: &str) -> Cow<'_, str> { if identifier.contains('"') { @@ -690,7 +694,7 @@ pub fn escape_double_quote(identifier: &str) -> Cow<'_, str> { Borrowed(identifier) } } -/// `feature = "vtab"` Dequote string +/// Dequote string pub fn dequote(s: &str) -> &str { if s.len() < 2 { return s; @@ -703,7 +707,7 @@ pub fn dequote(s: &str) -> &str { _ => s, } } -/// `feature = "vtab"` The boolean can be one of: +/// The boolean can be one of: /// ```text /// 1 yes true on /// 0 no false off @@ -1072,10 +1076,13 @@ fn alloc(s: &str) -> *mut c_char { } #[cfg(feature = "array")] +#[cfg_attr(docsrs, doc(cfg(feature = "array")))] pub mod array; #[cfg(feature = "csvtab")] +#[cfg_attr(docsrs, doc(cfg(feature = "csvtab")))] pub mod csvtab; #[cfg(feature = "series")] +#[cfg_attr(docsrs, doc(cfg(feature = "series")))] pub mod series; // SQLite >= 3.9.0 #[cfg(test)] diff --git a/src/vtab/series.rs b/src/vtab/series.rs index 31ef86f..0abd7e8 100644 --- a/src/vtab/series.rs +++ b/src/vtab/series.rs @@ -1,4 +1,4 @@ -//! `feature = "series"` Generate series virtual table. +//! Generate series virtual table. //! //! Port of C [generate series //! "function"](http://www.sqlite.org/cgi/src/finfo?name=ext/misc/series.c): @@ -15,7 +15,7 @@ use crate::vtab::{ }; use crate::{Connection, Error, Result}; -/// `feature = "series"` Register the "generate_series" module. +/// Register the "generate_series" module. pub fn load_module(conn: &Connection) -> Result<()> { let aux: Option<()> = None; conn.create_module("generate_series", eponymous_only_module::(), aux)