diff --git a/src/config.rs b/src/config.rs index 074fed0..797069e 100644 --- a/src/config.rs +++ b/src/config.rs @@ -6,33 +6,55 @@ use crate::ffi; use crate::{Connection, Result}; /// Database Connection Configuration Options +/// See [Database Connection Configuration Options](https://sqlite.org/c3ref/c_dbconfig_enable_fkey.html) for details. #[repr(i32)] #[allow(non_snake_case, non_camel_case_types)] #[non_exhaustive] pub enum DbConfig { //SQLITE_DBCONFIG_MAINDBNAME = 1000, /* const char* */ //SQLITE_DBCONFIG_LOOKASIDE = 1001, /* void* int int */ + /// Enable or disable the enforcement of foreign key constraints. SQLITE_DBCONFIG_ENABLE_FKEY = 1002, + /// Enable or disable triggers. SQLITE_DBCONFIG_ENABLE_TRIGGER = 1003, + /// Enable or disable the fts3_tokenizer() function which is part of the + /// FTS3 full-text search engine extension. SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER = 1004, // 3.12.0 //SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION = 1005, + /// In WAL mode, enable or disable the checkpoint operation before closing + /// the connection. SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE = 1006, // 3.16.2 - SQLITE_DBCONFIG_ENABLE_QPSG = 1007, // 3.20.0 - SQLITE_DBCONFIG_TRIGGER_EQP = 1008, // 3.22.0 + /// Activates or deactivates the query planner stability guarantee (QPSG). + SQLITE_DBCONFIG_ENABLE_QPSG = 1007, // 3.20.0 + /// Includes or excludes output for any operations performed by trigger + /// programs from the output of EXPLAIN QUERY PLAN commands. + SQLITE_DBCONFIG_TRIGGER_EQP = 1008, // 3.22.0 //SQLITE_DBCONFIG_RESET_DATABASE = 1009, + /// Activates or deactivates the "defensive" flag for a database connection. SQLITE_DBCONFIG_DEFENSIVE = 1010, // 3.26.0 + /// Activates or deactivates the "writable_schema" flag. #[cfg(feature = "modern_sqlite")] SQLITE_DBCONFIG_WRITABLE_SCHEMA = 1011, // 3.28.0 + /// Activates or deactivates the legacy behavior of the ALTER TABLE RENAME + /// command. #[cfg(feature = "modern_sqlite")] SQLITE_DBCONFIG_LEGACY_ALTER_TABLE = 1012, // 3.29 + /// Activates or deactivates the legacy double-quoted string literal + /// misfeature for DML statements only. #[cfg(feature = "modern_sqlite")] SQLITE_DBCONFIG_DQS_DML = 1013, // 3.29.0 + /// Activates or deactivates the legacy double-quoted string literal + /// misfeature for DDL statements. #[cfg(feature = "modern_sqlite")] SQLITE_DBCONFIG_DQS_DDL = 1014, // 3.29.0 + /// Enable or disable views. #[cfg(feature = "modern_sqlite")] SQLITE_DBCONFIG_ENABLE_VIEW = 1015, // 3.30.0 + /// Activates or deactivates the legacy file format flag. #[cfg(feature = "modern_sqlite")] SQLITE_DBCONFIG_LEGACY_FILE_FORMAT = 1016, // 3.31.0 + /// Tells SQLite to assume that database schemas (the contents of the + /// sqlite_master tables) are untainted by malicious content. #[cfg(feature = "modern_sqlite")] SQLITE_DBCONFIG_TRUSTED_SCHEMA = 1017, // 3.31.0 } diff --git a/src/error.rs b/src/error.rs index 35efaf1..c05f8cc 100644 --- a/src/error.rs +++ b/src/error.rs @@ -94,6 +94,7 @@ pub enum Error { #[allow(dead_code)] ModuleError(String), + /// An unwinding panic occurs in an UDF (user-defined function). #[cfg(feature = "functions")] UnwindingPanic, diff --git a/src/functions.rs b/src/functions.rs index b364f21..3531391 100644 --- a/src/functions.rs +++ b/src/functions.rs @@ -267,17 +267,26 @@ where } bitflags::bitflags! { - #[doc = "Function Flags."] - #[doc = "See [sqlite3_create_function](https://sqlite.org/c3ref/create_function.html) for details."] + /// Function Flags. + /// See [sqlite3_create_function](https://sqlite.org/c3ref/create_function.html) + /// and [Function Flags](https://sqlite.org/c3ref/c_deterministic.html) for details. #[repr(C)] pub struct FunctionFlags: ::std::os::raw::c_int { + /// Specifies UTF-8 as the text encoding this SQL function prefers for its parameters. const SQLITE_UTF8 = ffi::SQLITE_UTF8; + /// Specifies UTF-16 using little-endian byte order as the text encoding this SQL function prefers for its parameters. const SQLITE_UTF16LE = ffi::SQLITE_UTF16LE; + /// Specifies UTF-16 using big-endian byte order as the text encoding this SQL function prefers for its parameters. const SQLITE_UTF16BE = ffi::SQLITE_UTF16BE; + /// Specifies UTF-16 using native byte order as the text encoding this SQL function prefers for its parameters. const SQLITE_UTF16 = ffi::SQLITE_UTF16; + /// Means that the function always gives the same output when the input parameters are the same. const SQLITE_DETERMINISTIC = ffi::SQLITE_DETERMINISTIC; + /// Means that the function may only be invoked from top-level SQL. const SQLITE_DIRECTONLY = 0x0000_0008_0000; // 3.30.0 + /// Indicates to SQLite that a function may call `sqlite3_value_subtype()` to inspect the sub-types of its arguments. const SQLITE_SUBTYPE = 0x0000_0010_0000; // 3.30.0 + /// Means that the function is unlikely to cause problems even if misused. const SQLITE_INNOCUOUS = 0x0000_0020_0000; // 3.31.0 } } diff --git a/src/hooks.rs b/src/hooks.rs index ed556f5..53dc041 100644 --- a/src/hooks.rs +++ b/src/hooks.rs @@ -14,9 +14,13 @@ use crate::{Connection, InnerConnection}; #[repr(i32)] #[non_exhaustive] pub enum Action { + /// Unsupported / unexpected action UNKNOWN = -1, + /// DELETE command SQLITE_DELETE = ffi::SQLITE_DELETE, + /// INSERT command SQLITE_INSERT = ffi::SQLITE_INSERT, + /// UPDATE command SQLITE_UPDATE = ffi::SQLITE_UPDATE, } diff --git a/src/lib.rs b/src/lib.rs index 70dd54e..a774be1 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -53,7 +53,7 @@ //! Ok(()) //! } //! ``` -#![allow(unknown_lints)] +#![warn(missing_docs)] pub use libsqlite3_sys as ffi; @@ -806,19 +806,32 @@ impl fmt::Debug for Connection { } bitflags::bitflags! { - #[doc = "Flags for opening SQLite database connections."] - #[doc = "See [sqlite3_open_v2](http://www.sqlite.org/c3ref/open.html) for details."] + /// Flags for opening SQLite database connections. + /// See [sqlite3_open_v2](http://www.sqlite.org/c3ref/open.html) for details. #[repr(C)] pub struct OpenFlags: ::std::os::raw::c_int { + /// The database is opened in read-only mode. + /// If the database does not already exist, an error is returned. const SQLITE_OPEN_READ_ONLY = ffi::SQLITE_OPEN_READONLY; + /// The database is opened for reading and writing if possible, + /// or reading only if the file is write protected by the operating system. + /// In either case the database must already exist, otherwise an error is returned. const SQLITE_OPEN_READ_WRITE = ffi::SQLITE_OPEN_READWRITE; + /// The database is created if it does not already exist const SQLITE_OPEN_CREATE = ffi::SQLITE_OPEN_CREATE; + /// The filename can be interpreted as a URI if this flag is set. const SQLITE_OPEN_URI = 0x0000_0040; + /// The database will be opened as an in-memory database. const SQLITE_OPEN_MEMORY = 0x0000_0080; + /// The new database connection will use the "multi-thread" threading mode. const SQLITE_OPEN_NO_MUTEX = ffi::SQLITE_OPEN_NOMUTEX; + /// The new database connection will use the "serialized" threading mode. const SQLITE_OPEN_FULL_MUTEX = ffi::SQLITE_OPEN_FULLMUTEX; + /// The database is opened shared cache enabled. const SQLITE_OPEN_SHARED_CACHE = 0x0002_0000; + /// The database is opened shared cache disabled. const SQLITE_OPEN_PRIVATE_CACHE = 0x0004_0000; + /// The database filename is not allowed to be a symbolic link. const SQLITE_OPEN_NOFOLLOW = 0x0100_0000; } } diff --git a/src/row.rs b/src/row.rs index b33bdc0..1f8b1be 100644 --- a/src/row.rs +++ b/src/row.rs @@ -35,6 +35,8 @@ impl<'stmt> Rows<'stmt> { Ok((*self).get()) } + /// Map over this `Rows`, converting it to a [`Map`], which + /// implements `FallibleIterator`. pub fn map(self, f: F) -> Map<'stmt, F> where F: FnMut(&Row<'_>) -> Result, diff --git a/src/transaction.rs b/src/transaction.rs index e1b806e..5e649b7 100644 --- a/src/transaction.rs +++ b/src/transaction.rs @@ -6,8 +6,14 @@ use std::ops::Deref; #[derive(Copy, Clone)] #[non_exhaustive] pub enum TransactionBehavior { + /// DEFERRED means that the transaction does not actually start until the + /// database is first accessed. Deferred, + /// IMMEDIATE cause the database connection to start a new write + /// immediately, without waiting for a writes statement. Immediate, + /// EXCLUSIVE prevents other database connections from reading the database + /// while the transaction is underway. Exclusive, } diff --git a/src/types/from_sql.rs b/src/types/from_sql.rs index e8eadc5..131a638 100644 --- a/src/types/from_sql.rs +++ b/src/types/from_sql.rs @@ -86,6 +86,7 @@ pub type FromSqlResult = Result; /// fetching values as i64 and then doing the interpretation themselves or by /// defining a newtype and implementing `FromSql`/`ToSql` for it. pub trait FromSql: Sized { + /// Converts SQLite value into Rust value. fn column_result(value: ValueRef<'_>) -> FromSqlResult; } diff --git a/src/types/mod.rs b/src/types/mod.rs index d79ff82..92f5876 100644 --- a/src/types/mod.rs +++ b/src/types/mod.rs @@ -82,12 +82,19 @@ mod value_ref; #[derive(Copy, Clone)] pub struct Null; +/// SQLite data types. +/// See [Fundamental Datatypes](https://sqlite.org/c3ref/c_blob.html). #[derive(Clone, Debug, PartialEq)] pub enum Type { + /// NULL Null, + /// 64-bit signed integer Integer, + /// 64-bit IEEE floating point number Real, + /// String Text, + /// BLOB Blob, } diff --git a/src/types/to_sql.rs b/src/types/to_sql.rs index bec53f8..937c0f8 100644 --- a/src/types/to_sql.rs +++ b/src/types/to_sql.rs @@ -87,6 +87,7 @@ impl ToSql for ToSqlOutput<'_> { /// A trait for types that can be converted into SQLite values. pub trait ToSql { + /// Converts Rust value to SQLite value fn to_sql(&self) -> Result>; } diff --git a/src/types/value.rs b/src/types/value.rs index 332d78b..64dc203 100644 --- a/src/types/value.rs +++ b/src/types/value.rs @@ -109,6 +109,7 @@ where } impl Value { + /// Returns SQLite fundamental datatype. pub fn data_type(&self) -> Type { match *self { Value::Null => Type::Null, diff --git a/src/types/value_ref.rs b/src/types/value_ref.rs index 80d2457..2f32434 100644 --- a/src/types/value_ref.rs +++ b/src/types/value_ref.rs @@ -20,6 +20,7 @@ pub enum ValueRef<'a> { } impl ValueRef<'_> { + /// Returns SQLite fundamental datatype. pub fn data_type(&self) -> Type { match *self { ValueRef::Null => Type::Null, diff --git a/src/vtab/array.rs b/src/vtab/array.rs index 1ade815..0d32bd2 100644 --- a/src/vtab/array.rs +++ b/src/vtab/array.rs @@ -46,6 +46,7 @@ pub(crate) unsafe extern "C" fn free_array(p: *mut c_void) { let _: Array = Rc::from_raw(p as *const Vec); } +/// Array parameter / pointer pub type Array = Rc>; impl ToSql for Array { diff --git a/src/vtab/mod.rs b/src/vtab/mod.rs index d10dbed..bac2c94 100644 --- a/src/vtab/mod.rs +++ b/src/vtab/mod.rs @@ -205,7 +205,9 @@ impl VTabConnection { /// /// (See [SQLite doc](https://sqlite.org/c3ref/vtab.html)) pub unsafe trait VTab: Sized { + /// Client data passed to `Connection::create_module`. type Aux; + /// Specific cursor implementation type Cursor: VTabCursor; /// Establish a new connection to an existing virtual table. @@ -256,8 +258,9 @@ pub trait CreateVTab: VTab { } /// `feature = "vtab"` 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)] +#[allow(non_snake_case, non_camel_case_types, missing_docs)] #[non_exhaustive] pub enum IndexConstraintOp { SQLITE_INDEX_CONSTRAINT_EQ, @@ -329,6 +332,7 @@ impl IndexInfo { unsafe { (*self.0).nOrderBy as usize } } + /// Information about what parameters to pass to `VTabCursor.filter`. pub fn constraint_usage(&mut self, constraint_idx: usize) -> IndexConstraintUsage<'_> { let constraint_usages = unsafe { slice::from_raw_parts_mut((*self.0).aConstraintUsage, (*self.0).nConstraint as usize) @@ -495,6 +499,7 @@ pub unsafe trait VTabCursor: Sized { pub struct Context(*mut ffi::sqlite3_context); impl Context { + /// Set current cell value pub fn set_result(&mut self, value: &T) -> Result<()> { let t = value.to_sql()?; unsafe { set_result(self.0, &t) }; @@ -511,14 +516,17 @@ pub struct Values<'a> { } impl Values<'_> { + /// Returns the number of values. pub fn len(&self) -> usize { self.args.len() } + /// Returns `true` if there is no value. pub fn is_empty(&self) -> bool { self.args.is_empty() } + /// Returns value at `idx` pub fn get(&self, idx: usize) -> Result { let arg = self.args[idx]; let value = unsafe { ValueRef::from_value(arg) }; @@ -558,6 +566,7 @@ impl Values<'_> { } } + /// Turns `Values` into an iterator. pub fn iter(&self) -> ValueIter<'_> { ValueIter { iter: self.args.iter(), @@ -574,6 +583,7 @@ impl<'a> IntoIterator for &'a Values<'a> { } } +/// `Values` iterator. pub struct ValueIter<'a> { iter: slice::Iter<'a, *mut ffi::sqlite3_value>, }