Doc cleanup and "real" extensible enums

Author: sfackler

.circleci/config.yml

@@ -22,7 +22,7 @@ version: 2
 jobs:
   build:
     docker:
-      - image: rust:1.39.0
+      - image: rust:1.40.0
         environment:
           RUSTFLAGS: -D warnings
       - image: sfackler/rust-postgres-test:6

postgres-protocol/src/message/backend.rs

@@ -72,6 +72,7 @@ impl Header {
 }
 
 /// An enum representing Postgres backend messages.
+#[non_exhaustive]
 pub enum Message {
     AuthenticationCleartextPassword,
     AuthenticationGss,
@@ -104,8 +105,6 @@ pub enum Message {
     PortalSuspended,
     ReadyForQuery(ReadyForQueryBody),
     RowDescription(RowDescriptionBody),
-    #[doc(hidden)]
-    __ForExtensibility,
 }
 
 impl Message {

postgres-types/src/lib.rs

@@ -263,6 +263,7 @@ impl Type {
 
 /// Represents the kind of a Postgres type.
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
+#[non_exhaustive]
 pub enum Kind {
     /// A simple type like `VARCHAR` or `INTEGER`.
     Simple,
@@ -278,8 +279,6 @@ pub enum Kind {
     Domain(Type),
     /// A composite type along with information about its fields.
     Composite(Vec<Field>),
-    #[doc(hidden)]
-    __ForExtensibility,
 }
 
 /// Information about a field of a composite type.

tokio-postgres/src/config.rs

@@ -24,39 +24,36 @@ use tokio::io::{AsyncRead, AsyncWrite};
 
 /// Properties required of a session.
 #[derive(Debug, Copy, Clone, PartialEq)]
+#[non_exhaustive]
 pub enum TargetSessionAttrs {
     /// No special properties are required.
     Any,
     /// The session must allow writes.
     ReadWrite,
-    #[doc(hidden)]
-    __NonExhaustive,
 }
 
 /// TLS configuration.
 #[derive(Debug, Copy, Clone, PartialEq)]
+#[non_exhaustive]
 pub enum SslMode {
     /// Do not use TLS.
     Disable,
     /// Attempt to connect with TLS but allow sessions without.
     Prefer,
     /// Require the use of TLS.
     Require,
-    #[doc(hidden)]
-    __NonExhaustive,
 }
 
 /// Channel binding configuration.
 #[derive(Debug, Copy, Clone, PartialEq)]
+#[non_exhaustive]
 pub enum ChannelBinding {
     /// Do not use channel binding.
     Disable,
     /// Attempt to use channel binding but allow sessions without.
     Prefer,
     /// Require the use of channel binding.
     Require,
-    #[doc(hidden)]
-    __NonExhaustive,
 }
 
 #[derive(Debug, Clone, PartialEq)]
@@ -121,7 +118,7 @@ pub(crate) enum Host {
 /// # Url
 ///
 /// This format resembles a URL with a scheme of either `postgres://` or `postgresql://`. All components are optional,
-/// and the format accept query parameters for all of the key-value pairs described in the section above. Multiple
+/// and the format accepts query parameters for all of the key-value pairs described in the section above. Multiple
 /// host/port pairs can be comma-separated. Unix socket paths in the host section of the URL should be percent-encoded,
 /// as the path component of the URL specifies the database name.
 ///
@@ -425,7 +422,7 @@ impl Config {
 
     /// Connects to a PostgreSQL database over an arbitrary stream.
     ///
-    /// All of the settings other than `user`, `password`, `dbname`, `options`, and `application` name are ignored.
+    /// All of the settings other than `user`, `password`, `dbname`, `options`, and `application_name` name are ignored.
     pub async fn connect_raw<S, T>(
         &self,
         stream: S,

tokio-postgres/src/connect_raw.rs

@@ -197,7 +197,6 @@ fn can_skip_channel_binding(config: &Config) -> Result<(), Error> {
         config::ChannelBinding::Require => Err(Error::authentication(
             "server did not use channel binding".into(),
         )),
-        config::ChannelBinding::__NonExhaustive => unreachable!(),
     }
 }
 

tokio-postgres/src/connect_tls.rs

@@ -22,7 +22,6 @@ where
             return Ok(MaybeTlsStream::Raw(stream))
         }
         SslMode::Prefer | SslMode::Require => {}
-        SslMode::__NonExhaustive => unreachable!(),
     }
 
     let mut buf = BytesMut::new();

tokio-postgres/src/lib.rs

@@ -21,15 +21,12 @@
 //!         }
 //!     });
 //!
-//!     // Now we can prepare a simple statement that just returns its parameter.
-//!     let stmt = client.prepare("SELECT $1::TEXT").await?;
-//!
-//!     // And then execute it, returning a list of the resulting rows.
+//!     // Now we can execute a simple statement that just returns its parameter.
 //!     let rows = client
-//!         .query(&stmt, &[&"hello world"])
+//!         .query("SELECT $1::TEXT", &[&"hello world"])
 //!         .await?;
 //!
-//!     // Now we can check that we got back the same string we sent over.
+//!     // And then check that we got back the same string we sent over.
 //!     let value: &str = rows[0].get(0);
 //!     assert_eq!(value, "hello world");
 //!
@@ -201,6 +198,7 @@ impl Notification {
 
 /// An asynchronous message from the server.
 #[allow(clippy::large_enum_variant)]
+#[non_exhaustive]
 pub enum AsyncMessage {
     /// A notice.
     ///
@@ -210,20 +208,17 @@ pub enum AsyncMessage {
     ///
     /// Connections can subscribe to notifications with the `LISTEN` command.
     Notification(Notification),
-    #[doc(hidden)]
-    __NonExhaustive,
 }
 
 /// Message returned by the `SimpleQuery` stream.
+#[non_exhaustive]
 pub enum SimpleQueryMessage {
     /// A row of data.
     Row(SimpleQueryRow),
     /// A statement in the query has completed.
     ///
     /// The number of rows modified or selected is returned.
     CommandComplete(u64),
-    #[doc(hidden)]
-    __NonExhaustive,
 }
 
 fn slice_iter<'a>(

tokio-postgres/src/transaction.rs

@@ -184,13 +184,13 @@ impl<'a> Transaction<'a> {
     where
         T: ?Sized + ToStatement,
     {
-        self.bind_iter(statement, slice_iter(params)).await
+        self.bind_raw(statement, slice_iter(params)).await
     }
 
-    /// Like [`bind`], but takes an iterator of parameters rather than a slice.
+    /// A maximally flexible version of [`bind`].
     ///
     /// [`bind`]: #method.bind
-    pub async fn bind_iter<'b, T, I>(&self, statement: &T, params: I) -> Result<Portal, Error>
+    pub async fn bind_raw<'b, T, I>(&self, statement: &T, params: I) -> Result<Portal, Error>
     where
         T: ?Sized + ToStatement,
         I: IntoIterator<Item = &'b dyn ToSql>,
@@ -211,7 +211,9 @@ impl<'a> Transaction<'a> {
             .await
     }
 
-    /// The maximally flexible version of `query_portal`.
+    /// The maximally flexible version of [`query_portal`].
+    ///
+    /// [`query_portal`]: #method.query_portal
     pub async fn query_portal_raw(
         &self,
         portal: &Portal,