From 9d47d5109aeaad1c5d3c3fb940c48f0a90c66feb Mon Sep 17 00:00:00 2001
From: John Gallagher <jgallagher@bignerdranch.com>
Date: Tue, 24 May 2016 19:48:26 -0400
Subject: [PATCH] Add doc comments for BorrowedValue and friends.

---
 src/types/borrowed_value.rs | 18 ++++++++++++++++++
 src/types/from_sql.rs       |  1 +
 src/types/mod.rs            | 20 +++++++++++---------
 3 files changed, 30 insertions(+), 9 deletions(-)

diff --git a/src/types/borrowed_value.rs b/src/types/borrowed_value.rs
index cbbb977..f8e5068 100644
--- a/src/types/borrowed_value.rs
+++ b/src/types/borrowed_value.rs
@@ -2,15 +2,27 @@ use ::Result;
 use ::error::Error;
 use super::Value;
 
+/// A non-owning [dynamic type value](http://sqlite.org/datatype3.html). Typically the
+/// memory backing this value is owned by SQLite.
+///
+/// See [`Value`](enum.Value.html) for an owning dynamic type value.
+#[derive(Copy,Clone,Debug,PartialEq)]
 pub enum BorrowedValue<'a> {
+    /// The value is a `NULL` value.
     Null,
+    /// The value is a signed integer.
     Integer(i64),
+    /// The value is a floating point number.
     Real(f64),
+    /// The value is a text string.
     Text(&'a str),
+    /// The value is a blob of data
     Blob(&'a [u8]),
 }
 
 impl<'a> BorrowedValue<'a> {
+    /// If `self` is case `Integer`, returns the integral value. Otherwise, returns
+    /// `Err(Error::InvalidColumnType)`.
     pub fn as_i64(&self) -> Result<i64> {
         match *self {
             BorrowedValue::Integer(i) => Ok(i),
@@ -18,6 +30,8 @@ impl<'a> BorrowedValue<'a> {
         }
     }
 
+    /// If `self` is case `Real`, returns the floating point value. Otherwise, returns
+    /// `Err(Error::InvalidColumnType)`.
     pub fn as_f64(&self) -> Result<f64> {
         match *self {
             BorrowedValue::Real(f) => Ok(f),
@@ -25,6 +39,8 @@ impl<'a> BorrowedValue<'a> {
         }
     }
 
+    /// If `self` is case `Text`, returns the string value. Otherwise, returns
+    /// `Err(Error::InvalidColumnType)`.
     pub fn as_str(&self) -> Result<&str> {
         match *self {
             BorrowedValue::Text(ref t) => Ok(t),
@@ -32,6 +48,8 @@ impl<'a> BorrowedValue<'a> {
         }
     }
 
+    /// If `self` is case `Blob`, returns the byte slice. Otherwise, returns
+    /// `Err(Error::InvalidColumnType)`.
     pub fn as_blob(&self) -> Result<&[u8]> {
         match *self {
             BorrowedValue::Blob(ref b) => Ok(b),
diff --git a/src/types/from_sql.rs b/src/types/from_sql.rs
index c733f07..cddf287 100644
--- a/src/types/from_sql.rs
+++ b/src/types/from_sql.rs
@@ -1,6 +1,7 @@
 use super::{BorrowedValue, Value};
 use ::Result;
 
+/// A trait for types that can be created from a SQLite value.
 pub trait FromSql: Sized {
     fn column_result(value: BorrowedValue) -> Result<Self>;
 }
diff --git a/src/types/mod.rs b/src/types/mod.rs
index f8c8fba..d00693e 100644
--- a/src/types/mod.rs
+++ b/src/types/mod.rs
@@ -4,7 +4,9 @@
 //! the `ToSql` and `FromSql` traits are provided for the basic types that SQLite provides methods
 //! for:
 //!
-//! * C integers and doubles (`c_int` and `c_double`)
+//! * Integers (`i32` and `i64`; SQLite uses `i64` internally, so getting an `i32` will truncate
+//!   if the value is too large or too small).
+//! * Reals (`f64`)
 //! * Strings (`String` and `&str`)
 //! * Blobs (`Vec<u8>` and `&[u8]`)
 //!
@@ -15,12 +17,6 @@
 //! truncates timespecs to the nearest second. If you want different storage for timespecs, you can
 //! use a newtype. For example, to store timespecs as doubles:
 //!
-//! `ToSql` and `FromSql` are also implemented for `Option<T>` where `T` implements `ToSql` or
-//! `FromSql` for the cases where you want to know if a value was NULL (which gets translated to
-//! `None`). If you get a value that was NULL in SQLite but you store it into a non-`Option` value
-//! in Rust, you will get a "sensible" zero value - 0 for numeric types (including timespecs), an
-//! empty string, or an empty vector of bytes.
-//!
 //! ```rust,ignore
 //! extern crate rusqlite;
 //! extern crate libc;
@@ -51,6 +47,10 @@
 //!     }
 //! }
 //! ```
+//!
+//! `ToSql` and `FromSql` are also implemented for `Option<T>` where `T` implements `ToSql` or
+//! `FromSql` for the cases where you want to know if a value was NULL (which gets translated to
+//! `None`).
 
 pub use ffi::sqlite3_stmt;
 pub use ffi::sqlite3_column_type;
@@ -88,8 +88,10 @@ mod serde_json;
 #[derive(Copy,Clone)]
 pub struct Null;
 
-/// Dynamic type value (http://sqlite.org/datatype3.html)
-/// Value's type is dictated by SQLite (not by the caller).
+/// Owning [dynamic type value](http://sqlite.org/datatype3.html). Value's type is typically
+/// dictated by SQLite (not by the caller).
+///
+/// See [`BorrowedValue`](enum.BorrowedValue.html) for a non-owning dynamic type value.
 #[derive(Clone,Debug,PartialEq)]
 pub enum Value {
     /// The value is a `NULL` value.