Finish docs for tokio-postgres

Author: sfackler

tokio-postgres/src/config.rs

@@ -44,6 +44,8 @@ pub enum SslMode {
     Prefer,
     /// Require the use of TLS.
     Require,
+    #[doc(hidden)]
+    __NonExhaustive,
 }
 
 #[derive(Debug, Clone, PartialEq)]

tokio-postgres/src/impls.rs

@@ -213,3 +213,23 @@ impl Stream for SimpleQuery {
         self.0.poll()
     }
 }
+
+/// The future returned by `TransactionBuilder::build`.
+#[must_use = "futures do nothing unless polled"]
+pub struct Transaction<T>(pub(crate) proto::TransactionFuture<T, T::Item, T::Error>)
+where
+    T: Future,
+    T::Error: From<Error>;
+
+impl<T> Future for Transaction<T>
+where
+    T: Future,
+    T::Error: From<Error>,
+{
+    type Item = T::Item;
+    type Error = T::Error;
+
+    fn poll(&mut self) -> Poll<T::Item, T::Error> {
+        self.0.poll()
+    }
+}

tokio-postgres/src/lib.rs

@@ -87,7 +87,9 @@
 //! use futures::Future;
 //! use tokio_postgres::{Client, Error, Statement};
 //!
-//! fn pipelined_prepare(client: &mut Client) -> impl Future<Item = (Statement, Statement), Error = Error>
+//! fn pipelined_prepare(
+//!     client: &mut Client,
+//! ) -> impl Future<Item = (Statement, Statement), Error = Error>
 //! {
 //!     client.prepare("SELECT * FROM foo")
 //!         .join(client.prepare("INSERT INTO bar (id, name) VALUES ($1, $2)"))
@@ -99,7 +101,7 @@
 //! The client works with arbitrary `AsyncRead + AsyncWrite` streams. Convenience APIs are provided to handle the
 //! connection process, but these are gated by the `runtime` Cargo feature, which is enabled by default. If disabled,
 //! all dependence on the tokio runtime is removed.
-#![warn(rust_2018_idioms, clippy::all)]
+#![warn(rust_2018_idioms, clippy::all, missing_docs)]
 
 use bytes::IntoBuf;
 use futures::{Future, Poll, Stream};
@@ -406,32 +408,14 @@ pub struct Portal(proto::Portal);
 pub struct TransactionBuilder(proto::Client);
 
 impl TransactionBuilder {
-    pub fn build<T>(self, future: T) -> Transaction<T>
+    /// Returns a future which wraps another in a database transaction.
+    pub fn build<T>(self, future: T) -> impls::Transaction<T>
     where
         T: Future,
         // FIXME error type?
         T::Error: From<Error>,
     {
-        Transaction(proto::TransactionFuture::new(self.0, future))
-    }
-}
-
-#[must_use = "futures do nothing unless polled"]
-pub struct Transaction<T>(proto::TransactionFuture<T, T::Item, T::Error>)
-where
-    T: Future,
-    T::Error: From<Error>;
-
-impl<T> Future for Transaction<T>
-where
-    T: Future,
-    T::Error: From<Error>,
-{
-    type Item = T::Item;
-    type Error = T::Error;
-
-    fn poll(&mut self) -> Poll<T::Item, T::Error> {
-        self.0.poll()
+        impls::Transaction(proto::TransactionFuture::new(self.0, future))
     }
 }
 

tokio-postgres/src/proto/tls.rs

@@ -63,6 +63,7 @@ where
                     tls: state.tls,
                 })
             }
+            SslMode::__NonExhaustive => unreachable!(),
         }
     }
 

tokio-postgres/src/row.rs

@@ -93,6 +93,7 @@ where
     }
 }
 
+/// A row of data returned from the database by a query.
 pub struct Row {
     statement: proto::Statement,
     body: DataRowBody,
@@ -110,18 +111,28 @@ impl Row {
         })
     }
 
+    /// Returns information about the columns of data in the row.
     pub fn columns(&self) -> &[Column] {
         self.statement.columns()
     }
 
+    /// Determines if the row contains no values.
     pub fn is_empty(&self) -> bool {
         self.len() == 0
     }
 
+    /// Returns the number of values in the row.
     pub fn len(&self) -> usize {
         self.columns().len()
     }
 
+    /// Deserializes a value from the row.
+    ///
+    /// The value can be specified either by its numeric index in the row, or by its column name.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the index is out of bounds or if the value cannot be converted to the specified type.
     pub fn get<'a, I, T>(&'a self, idx: I) -> T
     where
         I: RowIndex + fmt::Display,
@@ -133,6 +144,7 @@ impl Row {
         }
     }
 
+    /// Like `Row::get`, but returns a `Result` rather than panicking.
     pub fn try_get<'a, I, T>(&'a self, idx: I) -> Result<T, Error>
     where
         I: RowIndex,
@@ -161,6 +173,7 @@ impl Row {
     }
 }
 
+/// A row of data returned from the database by a simple query.
 pub struct SimpleQueryRow {
     columns: Arc<[String]>,
     body: DataRowBody,
@@ -178,14 +191,23 @@ impl SimpleQueryRow {
         })
     }
 
+    /// Determines if the row contains no values.
     pub fn is_empty(&self) -> bool {
         self.len() == 0
     }
 
+    /// Returns the number of values in the row.
     pub fn len(&self) -> usize {
         self.columns.len()
     }
 
+    /// Returns a value from the row.
+    ///
+    /// The value can be specified either by its numeric index in the row, or by its column name.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the index is out of bounds or if the value cannot be converted to the specified type.
     pub fn get<I>(&self, idx: I) -> Option<&str>
     where
         I: RowIndex + fmt::Display,
@@ -196,6 +218,7 @@ impl SimpleQueryRow {
         }
     }
 
+    /// Like `SimpleQueryRow::get`, but returns a `Result` rather than panicking.
     pub fn try_get<I>(&self, idx: I) -> Result<Option<&str>, Error>
     where
         I: RowIndex,

tokio-postgres/src/socket.rs

@@ -13,6 +13,9 @@ enum Inner {
     Unix(UnixStream),
 }
 
+/// The standard stream type used by the crate.
+///
+/// Requires the `runtime` Cargo feature (enabled by default).
 #[derive(Debug)]
 pub struct Socket(Inner);
 

tokio-postgres/src/tls.rs

@@ -9,38 +9,55 @@ pub(crate) mod private {
     pub struct ForcePrivateApi;
 }
 
+/// Channel binding information returned from a TLS handshake.
 pub struct ChannelBinding {
     pub(crate) tls_server_end_point: Option<Vec<u8>>,
 }
 
 impl ChannelBinding {
+    /// Creates a `ChannelBinding` containing no information.
     pub fn none() -> ChannelBinding {
         ChannelBinding {
             tls_server_end_point: None,
         }
     }
 
+    /// Creates a `ChannelBinding` containing `tls-server-end-point` channel binding information.
     pub fn tls_server_end_point(tls_server_end_point: Vec<u8>) -> ChannelBinding {
         ChannelBinding {
             tls_server_end_point: Some(tls_server_end_point),
         }
     }
 }
 
+/// A constructor of `TlsConnect`ors.
+///
+/// Requires the `runtime` Cargo feature (enabled by default).
 #[cfg(feature = "runtime")]
 pub trait MakeTlsConnect<S> {
+    /// The stream type created by the `TlsConnect` implementation.
     type Stream: AsyncRead + AsyncWrite;
+    /// The `TlsConnect` implementation created by this type.
     type TlsConnect: TlsConnect<S, Stream = Self::Stream>;
+    /// The error type retured by the `TlsConnect` implementation.
     type Error: Into<Box<dyn Error + Sync + Send>>;
 
+    /// Creates a new `TlsConnect`or.
+    ///
+    /// The domain name is provided for certificate verification and SNI.
     fn make_tls_connect(&mut self, domain: &str) -> Result<Self::TlsConnect, Self::Error>;
 }
 
+/// An asynchronous function wrapping a stream in a TLS session.
 pub trait TlsConnect<S> {
+    /// The stream returned by the future.
     type Stream: AsyncRead + AsyncWrite;
+    /// The error type returned by the future.
     type Error: Into<Box<dyn Error + Sync + Send>>;
+    /// The future returned by the connector.
     type Future: Future<Item = (Self::Stream, ChannelBinding), Error = Self::Error>;
 
+    /// Returns a future performing a TLS handshake over the stream.
     fn connect(self, stream: S) -> Self::Future;
 
     #[doc(hidden)]
@@ -49,6 +66,9 @@ pub trait TlsConnect<S> {
     }
 }
 
+/// A `MakeTlsConnect` and `TlsConnect` implementation which simply returns an error.
+///
+/// This can be used when `sslmode` is `none` or `prefer`.
 #[derive(Debug, Copy, Clone)]
 pub struct NoTls;
 
@@ -77,6 +97,9 @@ impl<S> TlsConnect<S> for NoTls {
     }
 }
 
+/// The TLS "stream" type produced by the `NoTls` connector.
+///
+/// Since `NoTls` doesn't support TLS, this type is uninhabited.
 pub enum NoTlsStream {}
 
 impl Read for NoTlsStream {
@@ -103,6 +126,7 @@ impl AsyncWrite for NoTlsStream {
     }
 }
 
+/// The error returned by `NoTls`.
 #[derive(Debug)]
 pub struct NoTlsError(());