improve documentation

Author: s0lst1ce

src/guild.rs

@@ -1,11 +1,23 @@
+//! A [Guild]'s preferences (aka: configuration)
+//!
+//! Botanist is shipped with many features, some of which
+//! work out of the box (ex: `ping`). Other on the other hand
+//! rely on guild-specific datum. This data as a whole is called
+//! the [Guild]'s preferences or configuration.
+//! It notably includes the privilege (see [`Privilege`]) system
+//! but also conviniences such as welcome messages, administration
+//! channels or advertisement policy.
+//!
+//! [Guild]: serenity::model::guild::Guild
+
 use crate::as_pg_array;
 use async_recursion::async_recursion;
 use serenity::model::id::{ChannelId, GuildId, RoleId};
 use sqlx::{query, Executor, Postgres, Row};
 use std::convert::TryFrom;
 use thiserror::Error;
 
-/// Errors originating from the GuildConfig wrapper
+/// Errors originating from the `GuildConfig` wrapper
 #[derive(Error, Debug)]
 pub enum GuildConfigError {
     #[error("`{field:?}` can't be over 2000 chracters")]
@@ -22,8 +34,27 @@ type Result<Return> = std::result::Result<Return, GuildConfigError>;
 
 /// Wraps around a `guilds` row
 ///
-/// Most methods returning a [`std::result::Result`] do so only because the query to the DB may fail
-/// If another reason may cause it to fail, it will be documented
+/// [`GuildConfig`] provides an API covering every common use-case. When it doesn't piecing methods
+/// together is simple and safe. As much as possible it tries to issue as little queries as possible
+/// so you can confidently use the methods.
+///
+/// # Connection (`conn`) parameter.
+///
+/// For the sake of flexibility as little constraints as possible were put on the methods.
+/// The major example of this is the `conn` parameter which generally accepts anything that
+/// implements: [`sqlx::Executor`]. This means both [`sqlx::PgPool`] and
+/// [`sqlx::PgConnection`] can be used. However some methods need to issue multiple queries.
+/// As such it requires a `conn` that implements [`Copy`]. In those cases simply pass a `&PgPool`
+///
+/// # Errors
+///
+/// For simplicty's sake only methods that can give other errors than [`sqlx::Error`] have a section
+/// detailing the error.
+///
+/// All methods provided by [`Self`] return a `Result` which's [`Err`] variant is
+/// [`GuildConfigError`]. One of the later's variant wraps around [`sqlx::Error`] which is returned by
+/// every [`sqlx`] method that interacts with the database. These are all about database errors, which for the
+/// user of the library, should only be caused by incorrect setup (see [`crate`]).
 #[derive(Debug)]
 pub struct GuildConfig(GuildId);
 
@@ -56,7 +87,7 @@ impl GuildConfig {
     ///
     /// # Errors
     ///
-    /// Errors if a row with the same `id` already exists in the DB
+    /// Errors with [`GuildConfigError::AlreadyExists`] if a row with the same `id` already exists in the DB
     pub async fn new<'a, 'b, PgExec: Executor<'a, Database = Postgres> + Copy>(
         conn: PgExec,
         builder: GuildConfigBuilder<'b>,
@@ -450,6 +481,13 @@ impl ToString for Privilege {
     }
 }
 
+/// Builder for new configuration entries
+///
+/// This should only be used when the bot joins a new [Guild].
+/// This builder is used to quickly whip up a new configuration with sensible defaults
+/// that can be easilly overriden. For how to use see [`GuildConfig::new()`] and the tests.
+///
+/// [Guild]: serenity::model::guild::Guild`
 #[derive(Debug)]
 pub struct GuildConfigBuilder<'a> {
     id: GuildId,

src/lib.rs

@@ -1,9 +1,50 @@
+//! A wrapper around Botanist database scheme
+//!
+//! # Objective
+//!
+//! This crate was built with the intent to provide a safe wrapper around Botanist's
+//! database scheme. This way invariants remain true at all times, no other tool can
+//! mess the data in an incorrect way.
+//!
+//! Centralizing the interactions with the database also allows finer control over
+//! iterations of its scheme. On that note changes in the scheme are done through migrations scripts
+//! (see the `migrations`) folder. Hence the setup of the databse is made very simple with
+//! [`sqlx`]'s cli tool. Moreover deviations from the scheme provided by the migration scripts
+//! will be detected by the tests (see `tests/framework` and [`mod@sqlx::migrate`]).
+//!
+//! Finally providing a rust library allows [db_adapter] to provide useful abstractions.
+//!
+//! # Setup
+//! Setup is intended to be as simple as possible so if you find some way to simplify a step please open
+//! an issue.
+//! First of all make sure you have a posgresql database up and running. Search online for walkthroughs
+//!  if you don't know how. Then rename `.env-example` to `.env` and enter make sure you place your values
+//! in it.
+//! Now install [sqlx-cli] and run the migrations using `sqlx migrate run`. If you set up the DB and `.env`
+//! correctly you should be good to go!
+//! If you're only using the library you don't need to do anuything else but you could still
+//! run the tests just in case: `cargo t`.
+//!
+//! # Developement
+//!
+//! To contribute to [db_adapter] you should setup the test environement. In addition to the previous section's
+//! steps you should setup another DB for the tests and refer it in `.env`. From there you can dive in the code!
+//! Just make sure you don't break any invariants and remember to respect semver. You are also expected
+//! to document and tests any item added to the public API.
+//!
+//! [sqlx-cli]: https://github.com/launchbadge/sqlx/tree/master/sqlx-cli
+//! [db_adapter]: [`self`]
+
 use sqlx::postgres::PgPool;
 use std::env;
 use std::fmt::Write;
 
 pub mod guild;
+pub mod slap;
 
+/// Creates a [connection pool] to the database
+///
+/// [connection pool]: sqlx::postgres::PgPool
 pub async fn establish_connection() -> PgPool {
     dotenv::dotenv().ok();
     PgPool::connect(&env::var("DATABASE_URL").expect("DATABASE_URL was not set"))
@@ -25,18 +66,3 @@ pub(crate) fn as_pg_array(ids: &[i64]) -> String {
     write!(array, "}}'").unwrap();
     array
 }
-
-/*
-pub(crate) fn to_comma_separated(ids: &[i64]) -> String {
-    let mut array = String::new();
-    if ids.is_empty() {
-        return array;
-    }
-    for int in ids {
-        write!(array, "{},", int).unwrap()
-    }
-    array.pop(); //removing the trailing comma
-
-    array
-}
-*/