Fill in some missing docs (#179)

butane/src/lib.rs

@@ -5,6 +5,7 @@
 //! The fact that it is backed by a SQL database is mostly an implementation detail to the API consumer.
 
 #![deny(missing_docs)]
+
 pub use butane_codegen::{butane_type, dataresult, model, FieldType};
 pub use butane_core::custom;
 pub use butane_core::fkey::ForeignKey;

butane_core/src/codegen/dbobj.rs

@@ -10,7 +10,7 @@ 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>,
@@ -263,10 +263,12 @@ pub fn add_fieldexprs(ast_struct: &ItemStruct, config: &Config) -> TokenStream2
     let fields_type = fields_type(tyname);
     quote!(
         impl #tyname {
+            /// Get fields.
             pub fn fields() -> #fields_type {
                 #fields_type::default()
             }
         }
+        /// Helper struct for butane model.
         #vis struct #fields_type {
         }
         impl #fields_type {
@@ -321,6 +323,7 @@ fn fieldexpr_func(
     };
     let fnid = Ident::new(&format!("{fid}"), f.span());
     quote!(
+        /// Create query expression.
         #vis fn #fnid(&self) -> #field_expr_type {
             #field_expr_ctor
         }

butane_core/src/codegen/mod.rs

@@ -19,6 +19,7 @@ const MANY_TYNAMES: [&str; 2] = ["Many", "butane::Many"];
 const FKEY_TYNAMES: [&str; 2] = ["ForeignKey", "butane::ForeignKey"];
 const AUTOPK_TYNAMES: [&str; 2] = ["AutoPk", "butane::AutoPk"];
 
+/// Create a compiler error.
 #[macro_export]
 macro_rules! make_compile_error {
     ($span:expr=> $($arg:tt)*) => ({

butane_core/src/custom.rs

@@ -5,6 +5,8 @@
 //! source repository. Not supported for the Sqlite backend as Sqlite
 //! supports a very limited set of types to begin with.
 
+#![allow(missing_docs)]
+
 use std::fmt;
 
 use serde::{Deserialize, Serialize};

butane_core/src/db/mod.rs

@@ -12,6 +12,8 @@
 //!    what a `BackendConnection` can do, but allows using a single concrete type that is not tied to a particular
 //!    database backend. It is returned by the `connect` method.
 
+#![allow(missing_docs)]
+
 use std::borrow::Cow;
 use std::fmt::Debug;
 use std::fs;

butane_core/src/lib.rs

@@ -1,5 +1,9 @@
+//! Library providing functionality used by butane macros and tools.
+
 #![allow(clippy::iter_nth_zero)]
 #![allow(clippy::upper_case_acronyms)] //grandfathered, not going to break API to rename
+#![deny(missing_docs)]
+
 use std::cmp::{Eq, PartialEq};
 use std::default::Default;
 
@@ -25,6 +29,7 @@ use db::{BackendRow, Column, ConnectionMethods};
 pub use query::Query;
 pub use sqlval::{AsPrimaryKey, FieldType, FromSql, PrimaryKeyType, SqlVal, SqlValRef, ToSql};
 
+/// Result type that uses [`crate::Error`].
 pub type Result<T> = std::result::Result<T, crate::Error>;
 
 /// A type which may be the result of a database query.
@@ -37,10 +42,15 @@ pub type Result<T> = std::result::Result<T, crate::Error>;
 pub trait DataResult: Sized {
     /// Corresponding object type.
     type DBO: DataObject;
+
+    /// Metadata for eaCH column.
     const COLUMNS: &'static [Column];
+
+    /// Load an object from a database backend row.
     fn from_row<'a>(row: &(dyn BackendRow + 'a)) -> Result<Self>
     where
         Self: Sized;
+
     /// Create a blank query (matching all rows) for this type.
     fn query() -> Query<Self>;
 }
@@ -52,6 +62,7 @@ pub trait DataResult: Sized {
 pub trait DataObject: DataResult<DBO = Self> {
     /// The type of the primary key field.
     type PKType: PrimaryKeyType;
+    /// Link to a generated struct providing query helpers for each field.
     type Fields: Default;
     /// The name of the primary key column.
     const PKCOL: &'static str;
@@ -60,6 +71,7 @@ pub trait DataObject: DataResult<DBO = Self> {
     /// Whether or not this model uses an automatic primary key set on
     /// the first save.
     const AUTO_PK: bool;
+
     /// Get the primary key
     fn pk(&self) -> &Self::PKType;
     /// Find this object in the database based on primary key.
@@ -95,6 +107,7 @@ pub trait DataObject: DataResult<DBO = Self> {
 }
 
 /// Butane errors.
+#[allow(missing_docs)]
 #[derive(Debug, ThisError)]
 pub enum Error {
     #[error("No such object exists")]
@@ -187,19 +200,25 @@ impl From<rusqlite::types::FromSqlError> for Error {
 /// See also [`SqlVal`].
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
 pub enum SqlType {
+    /// Boolean
     Bool,
     /// 4 bytes
     Int,
     /// 8 bytes
     BigInt,
     /// 8 byte float
     Real,
+    /// String
     Text,
     #[cfg(feature = "datetime")]
+    /// Timestamp
     Timestamp,
+    /// Blob
     Blob,
     #[cfg(feature = "json")]
+    /// JSON
     Json,
+    /// Custom SQL type
     Custom(SqlTypeCustom),
 }
 impl std::fmt::Display for SqlType {
@@ -230,11 +249,15 @@ pub use log::warn;
 #[cfg(not(feature = "log"))]
 mod btlog {
     // this module is just for grouping -- macro_export puts them in the crate root
+
+    /// Noop for when feature log is not enabled.
     #[macro_export]
     macro_rules! debug {
         (target: $target:expr, $($arg:tt)+) => {};
         ($($arg:tt)+) => {};
     }
+
+    /// Noop for when feature log is not enabled.
     #[macro_export]
     macro_rules! warn {
         (target: $target:expr, $($arg:tt)+) => {};

butane_core/src/migrations/mod.rs

@@ -1,5 +1,8 @@
 //! For working with migrations. If using the butane CLI tool, it is
 //! not necessary to use these types directly.
+
+#![allow(missing_docs)]
+
 use std::path::Path;
 
 use fallible_iterator::FallibleIterator;

butane_core/src/query/mod.rs

@@ -2,6 +2,8 @@
 //! the `query!`, `filter!`, and `find!` macros instead of using this
 //! module directly.
 
+#![allow(missing_docs)]
+
 use std::borrow::Cow;
 use std::marker::PhantomData;
 

butane_core/src/sqlval.rs

@@ -1,5 +1,7 @@
 //! Types and traits for interacting with a value that can be stored in the database.
 
+#![allow(missing_docs)]
+
 use std::borrow::Cow;
 #[cfg(feature = "json")]
 use std::collections::{BTreeMap, HashMap};

examples/getting_started/src/lib.rs

@@ -1,5 +1,7 @@
 //! Common helpers for the getting_started example CLI.
 
+#![deny(missing_docs)]
+
 pub mod butane_migrations;
 pub mod models;