Improve butane_core docstrings (#401)

Author: jayvdb

butane_core/src/autopk.rs

@@ -7,9 +7,10 @@ use serde::{Deserialize, Serialize};
 
 use super::{FieldType, FromSql, PrimaryKeyType, Result, SqlType, SqlVal, SqlValRef, ToSql};
 
-/// Wrapper around a [PrimaryKeyType] to indicate the the primary key
-/// will be initialized automatically when the object is created in
-/// the database.
+/// Used to implement a primary key that is automatically populated by the backend.
+///
+/// Wrapper around a [`PrimaryKeyType`] to indicate the primary key will be initialized automatically.
+///
 /// Dereferences to an `Option<T>`.
 #[derive(Clone, Debug, Default, Serialize, Deserialize)]
 pub struct AutoPk<T: PrimaryKeyType> {
@@ -25,8 +26,9 @@ impl<T: PrimaryKeyType> AutoPk<T> {
         Self::default()
     }
 
-    /// Create an initialized primary key value for a previously saved
-    /// object. You do not usually need to call this directly (it will
+    /// Create an initialized primary key value for a previously saved object.
+    ///
+    /// You do not usually need to call this directly (it will
     /// happen implicitly when you load from the database).
     fn with_value(val: T) -> Self {
         AutoPk { inner: Some(val) }
@@ -53,10 +55,11 @@ impl<T: PrimaryKeyType> FromSql for AutoPk<T> {
         Ok(AutoPk::with_value(T::from_sql_ref(val)?))
     }
 
-    /// Used to convert a SqlVal into another type. The default
-    /// implementation calls `Self::from_sql_ref(val.as_ref())`, which
-    /// may be inefficient. This method is chiefly used only for
-    /// primary keys: a more efficient implementation is unlikely to
+    /// Used to convert a `SqlVal` into another type.
+    ///
+    /// The default implementation calls `Self::from_sql_ref(val.as_ref())`, which
+    /// may be inefficient. This method is chiefly used only
+    /// for primary keys: a more efficient implementation is unlikely to
     /// provide benefits for types not used as primary keys.
     fn from_sql(val: SqlVal) -> Result<Self>
     where

butane_core/src/codegen/dbobj.rs

@@ -11,13 +11,13 @@ use super::{
 use crate::migrations::adb::{DeferredSqlType, TypeIdentifier, MANY_SUFFIX};
 use crate::SqlType;
 
-/// Configuration that can be specified with attributes to override default behavior
+/// Configuration that can be specified with attributes to override default behavior.
 #[derive(Clone, Debug, Default)]
 pub struct Config {
     pub table_name: Option<String>,
 }
 
-/// Code generation to implement the DataObject trait for a model
+/// Code generation to implement the [`DataObject`] trait for a model.
 pub fn impl_dbobject(ast_struct: &ItemStruct, config: &Config) -> TokenStream2 {
     let tyname = &ast_struct.ident;
     let tablelit = make_tablelit(config, tyname);
@@ -157,7 +157,7 @@ pub fn impl_dbobject(ast_struct: &ItemStruct, config: &Config) -> TokenStream2 {
     )
 }
 
-/// Code generation to implement the DataResult trait for a model
+/// Code generation to implement the DataResult trait for a model.
 pub fn impl_dataresult(ast_struct: &ItemStruct, dbo: &Ident, config: &Config) -> TokenStream2 {
     let tyname = &ast_struct.ident;
     let numdbfields = fields(ast_struct).filter(|f| is_row_field(f)).count();
@@ -413,8 +413,9 @@ fn verify_fields(ast_struct: &ItemStruct) -> Option<TokenStream2> {
     None
 }
 
-/// Builds code for pushing SqlVals for each column satisfying predicate into a vec called `values`
-/// that excludes any auto values.
+/// Build code to push [`SqlVal`]s for each column satisfying `predicate` into a `Vec` called `values`.
+///
+/// It excludes any auto values.
 fn push_values<P>(ast_struct: &ItemStruct, mut predicate: P) -> Vec<TokenStream2>
 where
     P: FnMut(&Field) -> bool,

butane_core/src/codegen/mod.rs

@@ -240,7 +240,7 @@ where
     }
 }
 
-/// Create a [`struct@LitStr`] (UTF-8 string literal) from an [Ident].
+/// Create a [`struct@LitStr`] (UTF-8 string literal) from an [`Ident`].
 pub fn make_ident_literal_str(ident: &Ident) -> LitStr {
     let as_str = ident.strip_raw().to_string();
     make_lit(&as_str)
@@ -374,13 +374,13 @@ fn is_option(field: &Field) -> bool {
     get_type_argument(&field.ty, "Option").is_some()
 }
 
-/// Check for special fields which won't correspond to rows and don't
-/// implement FieldType
+/// Check for special fields which won't correspond to rows and don't implement [`FieldType`].
 fn is_row_field(f: &Field) -> bool {
     !is_many_to_many(f)
 }
 
-/// Gets the type argument of a type.
+/// Get the type argument of a type.
+///
 /// E.g. for `Foo<T>`, returns `T`.
 fn get_type_argument<'a>(ty: &'a syn::Type, tyname: &'static str) -> Option<&'a syn::Path> {
     let path = match ty {
@@ -390,7 +390,8 @@ fn get_type_argument<'a>(ty: &'a syn::Type, tyname: &'static str) -> Option<&'a
     get_path_argument(path, tyname)
 }
 
-/// Gets the type argument of a path.
+/// Get the type argument of a path.
+///
 /// E.g. for `Foo<T>``, returns `T`.
 fn get_path_argument<'a>(path: &'a syn::Path, tyname: &str) -> Option<&'a syn::Path> {
     if let Some(resolved) = PATH_RESOLVER.resolve(path) {
@@ -430,9 +431,9 @@ fn get_foreign_sql_type(path: &syn::Path, tyname: &str) -> Option<DeferredSqlTyp
     })
 }
 
-/// Determine whether a type refers to a data type that is supported directly by butane,
-/// or is a custom defined struct.
-/// It looks inside an [Option] or [crate::fkey::ForeignKey] to determine the inner type.
+/// Determine whether a type refers to a data type that is supported directly by butane, or is a custom defined struct.
+///
+/// It looks inside an `Option` or [`ForeignKey`](crate::fkey::ForeignKey) to determine the inner type.
 pub fn get_deferred_sql_type(path: &syn::Path) -> DeferredSqlType {
     get_primitive_sql_type(path)
         .or_else(|| get_option_sql_type(path))

butane_core/src/custom.rs

@@ -14,14 +14,14 @@ use serde::{Deserialize, Serialize};
 #[cfg(feature = "pg")]
 use tokio_postgres as postgres;
 
-/// For use with [SqlType::Custom](crate::SqlType)
+/// For use with [`SqlType::Custom`](crate::SqlType).
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
 pub enum SqlTypeCustom {
     #[cfg(feature = "pg")]
     Pg(#[serde(with = "pgtypeser")] tokio_postgres::types::Type),
 }
 
-/// For use with [SqlVal::Custom](crate::SqlVal)
+/// For use with [`SqlVal::Custom`](crate::SqlVal).
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
 pub enum SqlValCustom {
     #[cfg(feature = "pg")]
@@ -89,7 +89,7 @@ impl postgres::types::ToSql for SqlValCustom {
     postgres::types::to_sql_checked!();
 }
 
-/// For use with [SqlValRef::Custom](crate::SqlValRef)
+/// For use with [`SqlValRef::Custom`](crate::SqlValRef).
 #[derive(Clone, Debug)]
 pub enum SqlValRefCustom<'a> {
     /// Used with Postgres, but suitable only for input (e.g. input to

butane_core/src/db/adapter.rs

@@ -42,8 +42,10 @@ impl AsyncAdapterEnv {
         }
     }
 
-    /// Invokes a blocking function `func` as if it were async. This
-    /// is implemented by running it on the special thread created when the `AsyncAdapterEnv` was created.
+    /// Invokes a blocking function `func` as if it were async.
+    ///
+    /// This is implemented by running it on the special thread created
+    /// when the `AsyncAdapterEnv` was created.
     async fn invoke<'c, 's, 'result, F, T, U>(
         &'s self,
         context: &SyncSendPtrMut<T>,
@@ -153,8 +155,9 @@ impl Drop for AsyncAdapterEnv {
     }
 }
 
-/// Wrapper around a raw pointer that we assert is [Send].  Needless to
-/// say, this requires care. See comments on `AsyncAdapterEnv::invoke`
+/// Wrapper around a raw pointer that we assert is [`Send`].
+///
+/// Needless to say, this requires care. See comments on [`AsyncAdapterEnv::invoke`]
 /// for why we believe this to be sound.
 struct SendPtr<T: ?Sized> {
     inner: *const T,
@@ -166,7 +169,7 @@ impl<T: ?Sized> SendPtr<T> {
 }
 unsafe impl<T: ?Sized> Send for SendPtr<T> {}
 
-/// Like [SendPtrMut] but we also assert that it is [Sync]
+/// Like [`SendPtrMut`] but we also assert that it is [`Sync`].
 struct SyncSendPtrMut<T: ?Sized> {
     inner: *mut T,
 }
@@ -205,7 +208,7 @@ pub(super) struct AsyncAdapter<T: ?Sized> {
 }
 
 impl<T: ?Sized> AsyncAdapter<T> {
-    /// Create a new AsyncAdapter with the given context and using the same `env` as self. Not a public method.
+    /// Create an `AsyncAdapter` with the given context, using the same `env` as self.
     fn create_with_same_env<U: ?Sized>(&self, context_ptr: SyncSendPtrMut<U>) -> AsyncAdapter<U> {
         AsyncAdapter {
             env: self.env.clone(),
@@ -248,7 +251,7 @@ impl<T: ?Sized> AsyncAdapter<T> {
 }
 
 impl<T> AsyncAdapter<T> {
-    /// Create a new async adapter using `create_context` to create an instance of the inner type `T`.
+    /// Create an async adapter using `create_context` to create an instance of the inner type `T`.
     pub(super) fn new<F>(create_context: F) -> Result<Self>
     where
         Self: Sized,
@@ -389,8 +392,9 @@ where
         ok_or_panic_with_adapter_error(self.invoke_blocking(|conn| Ok(conn.backend_name())))
     }
 
-    /// Tests if the connection has been closed. Backends which do not
-    /// support this check should return false.
+    /// Tests if the connection has been closed.
+    ///
+    /// Backends which do not support this check should return `false`.
     fn is_closed(&self) -> bool {
         ok_or_panic_with_adapter_error(self.invoke_blocking(|conn| Ok(conn.is_closed())))
     }
@@ -442,8 +446,9 @@ where
     }
 }
 
-/// Create an async connection using the synchronous `connect` method of `backend`. Use this when authoring
-/// a backend which doesn't natively support async.
+/// Create an async connection via the synchronous `connect` method of `backend`.
+///
+/// Use this when authoring a backend which doesn't natively support async.
 pub async fn connect_async_via_sync<B>(backend: &B, conn_str: &str) -> Result<ConnectionAsync>
 where
     B: Backend + Clone + 'static,

butane_core/src/db/connmethods.rs

@@ -8,10 +8,11 @@ use async_trait::async_trait;
 use crate::query::{BoolExpr, Expr, Order};
 use crate::{Result, SqlType, SqlVal, SqlValRef};
 
-/// Methods available on a database connection. Most users do not need
-/// to call these methods directly and will instead use methods on
-/// [DataObject][crate::DataObject] or the `query!` macro. This trait is
-/// implemented by both database connections and transactions.
+/// Methods available on a database connection.
+///
+/// Most users do not need to call these methods directly and will instead
+/// use methods on [`DataObject`][`crate::DataObject`] or the `query!` macro.
+/// This trait is implemented by both database connections and transactions.
 #[maybe_async_cfg::maybe(
     sync(keep_self),
     async(feature = "async", self = "ConnectionMethodsAsync"),
@@ -69,8 +70,9 @@ pub trait ConnectionMethods: super::internal::AsyncRequiresSync {
     async fn has_table(&self, table: &str) -> Result<bool>;
 }
 
-/// Represents a database column. Most users do not need to use this
-/// directly.
+/// Represents a database column.
+///
+/// Most users do not need to use this directly.
 #[derive(Clone, Debug)]
 pub struct Column {
     name: &'static str,
@@ -88,8 +90,9 @@ impl Column {
     }
 }
 
-/// Backend-specific row abstraction. Only implementors of new
-/// backends need use this trait directly.
+/// Backend-specific row abstraction.
+///
+/// Only implementors of new backends need use this trait directly.
 pub trait BackendRow {
     fn get(&self, idx: usize, ty: SqlType) -> Result<SqlValRef<'_>>;
     fn len(&self) -> usize;
@@ -99,9 +102,10 @@ pub trait BackendRow {
     }
 }
 
-/// Abstraction of rows returned from a query. Most users do not need
-/// to deal with this directly and should use the `query!` macro or
-/// [Query](crate::query::Query) type.
+/// Abstraction of rows returned from a query.
+///
+/// Most users do not need to deal with this directly and should use
+/// the `query!` macro or [`Query`](crate::query::Query) type.
 pub trait BackendRows {
     // Advance to the next item and get it
     fn next<'a>(&'a mut self) -> Result<Option<&'a (dyn BackendRow + 'a)>>;

butane_core/src/db/dummy.rs

@@ -12,8 +12,9 @@ use crate::{Error, Result, SqlVal, SqlValRef};
 #[derive(Clone, Debug)]
 struct DummyBackend {}
 
-/// Provides a backend implementation which fails all operations with [Error::PoisonedConnection].
-/// Exists so that it can be returned from the [BackendConnection] implementation of [DummyConnection].
+/// Provides a backend implementation which fails all operations with [`Error::PoisonedConnection`].
+///
+/// Exists so that it can be returned from the [`BackendConnection`] implementation of [`DummyConnection`].
 #[async_trait]
 impl Backend for DummyBackend {
     fn name(&self) -> &'static str {
@@ -33,10 +34,11 @@ impl Backend for DummyBackend {
     }
 }
 
-/// Provides a connection implementation which fails all operations with [Error::PoisonedConnection].
+/// Provides a connection implementation which fails all operations with [`Error::PoisonedConnection`].
+///
+/// [`ConnectionAsync`] provides a `with_sync` method which allows running a non-async function.
+/// which takes synchronous [`Connection`]. This is implemented using [`std::mem::swap`] to satisfy the borrow checker.
 ///
-/// [ConnectionAsync] provides a `with_sync` method which allows running a non-async function
-/// which takes synchronous [Connection]. This is implemented using std::mem::swap to satisfy the borrow checker.
 /// The original async connection is replaced with a dummy one while the sync operation is being run.
 #[derive(Clone, Debug)]
 pub(crate) struct DummyConnection {}

butane_core/src/db/helper.rs

@@ -28,8 +28,10 @@ pub fn quote_reserved_word(word: &str) -> Cow<'_, str> {
     }
 }
 
-/// Writes to `w` the SQL to express the expression given in `expr`. Values contained in `expr` are rendered
-/// as placeholders in the SQL string and the actual values are added to `values`.
+/// Writes to `w` the SQL to express the expression given in `expr`.
+///
+/// Values contained in `expr` are rendered as placeholders in the SQL
+/// string and the actual values are added to `values`.
 pub fn sql_for_expr<F, P, W>(expr: Expr, f: F, values: &mut Vec<SqlVal>, pls: &mut P, w: &mut W)
 where
     F: Fn(Expr, &mut Vec<SqlVal>, &mut P, &mut W),
@@ -169,8 +171,7 @@ pub fn sql_insert_with_placeholders(
     }
 }
 
-/// Writes to `w` the SQL of an UPDATE to `table` of `columns` using values in `pls`,
-/// for the row uniquely identified by `pkcol`.
+/// Write to `w` a SQL UPDATE to `table` of `columns` using values in `pls`, for the row uniquely identified by `pkcol`.
 pub fn sql_update_with_placeholders(
     table: &str,
     pkcol: Column,