Fix some minor weirdness when Pilcrow is (unwisely) used as a library.

Pilcrow isn't meant to be used as a library, and the only public interface the `pilcrow` lib crate exposes is the CLI entry point. However, we will likely be publishing Pilcrow via crates.io (among other options) one day, and so it will _be usable_ as a library if someone's desperate enough to try. To that end, let's try to be good citizens.

This change fixes two issues:

* The docs contained links to internal items, which are not actually included in the library documentation. The links are simply removed; the uses of those items were already private anyways.

* The CLI `Error` type is no longer part of the public interface, using `impl Trait` (`impl std::error::Error`) shenanigans to hide the error type from callers. (To be clear, this would be _extremely_ rude in code intended for library use.) This frees us up to change the structure of the error type - or to replace it entirely - without making the world's most pedantic semver change in the process.

Merges lib-crate-weirdness into main.

4 files changed, 5 insertions, 22 deletions

diff --git a/src/cli.rs b/src/cli.rs
index 57c5c07..703bf19 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -84,11 +84,10 @@ impl Args {
     /// # Errors
     ///
     /// Will return `Err` if the server is unable to start, or terminates
-    /// prematurely. The specific [`Error`] variant will expose the cause
+    /// prematurely. The returned error contains a user-facing explanation
     /// of the failure.
-    pub async fn run(self) -> Result<(), Error> {
+    pub async fn run(self) -> Result<(), impl std::error::Error> {
         self.umask.set();
-
         let pool = self.pool().await?;
 
         let app = App::from(pool);
@@ -104,7 +103,7 @@ impl Args {
         println!("{started_msg}");
         serve.await?;
 
-        Ok(())
+        Result::<_, Error>::Ok(())
     }
 
     async fn listener(&self) -> io::Result<net::TcpListener> {
@@ -138,14 +137,10 @@ fn started_msg(listener: &net::TcpListener) -> io::Result<String> {
     Ok(format!("listening on http://{local_addr}/"))
 }
 
-/// Errors that can be raised by [`Args::run`].
 #[derive(Debug, thiserror::Error)]
 #[error(transparent)]
-pub enum Error {
-    /// Failure due to `io::Error`. See [`io::Error`].
+enum Error {
     Io(#[from] io::Error),
-    /// Failure due to a database initialization error. See [`db::Error`].
     Database(#[from] db::Error),
-    /// Failure due to invalid umask-related options.
     Umask(#[from] umask::Error),
 }
diff --git a/src/db/mod.rs b/src/db/mod.rs
index 632cd9c..99b8986 100644
--- a/src/db/mod.rs
+++ b/src/db/mod.rs
@@ -102,16 +102,12 @@ async fn migration_replaced(
     Ok(())
 }
 
-/// Errors occurring during database setup.
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
-    /// Failure due to a database error. See [`sqlx::Error`].
     #[error(transparent)]
     Database(#[from] sqlx::Error),
-    /// Failure because an existing database backup already exists.
     #[error("backup from a previous failed migration already exists: {0}")]
     BackupExists(String),
-    /// Failure due to a database backup error. See [`backup::Error`].
     #[error(transparent)]
     Backup(#[from] backup::Error),
     #[error("migration failed: {1}\nrestoring backup failed: {0}")]
@@ -120,12 +116,8 @@ pub enum Error {
         "migration failed: {1}\nrestoring from backup succeeded, but deleting backup failed: {0}"
     )]
     Drop(sqlx::Error, sqlx::migrate::MigrateError),
-    /// Failure due to a database migration error. See
-    /// [`sqlx::migrate::MigrateError`].
     #[error(transparent)]
     Migration(#[from] sqlx::migrate::MigrateError),
-    /// Failure because the database contains a migration from an unsupported
-    /// schema version.
     #[error("database contains rejected migration {0}:{1}, move it aside")]
     Rejected(String, String),
 }
diff --git a/src/main.rs b/src/main.rs
index 427294e..b8981d0 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -3,7 +3,7 @@ use clap::Parser;
 use pilcrow::cli;
 
 #[tokio::main]
-async fn main() -> Result<(), cli::Error> {
+async fn main() -> Result<(), impl std::error::Error> {
     let args = cli::Args::parse();
     args.run().await
 }
diff --git a/src/umask.rs b/src/umask.rs
index 32a82ad..6aef33a 100644
--- a/src/umask.rs
+++ b/src/umask.rs
@@ -100,15 +100,11 @@ impl fmt::Display for Umask {
     }
 }
 
-/// Errors occurring during umask option parsing.
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
-    /// Failed to parse a umask value from the input.
     #[error(transparent)]
     Parse(#[from] std::num::ParseIntError),
 
-    /// The provided umask contained invalid bits. (See the constants associated with [`Mode`] for
-    /// valid umask bits.)
     // We dont need to hold onto the actual umask value here - Clap does that for us, and prints
     // the value as the user input it, which beats anything we could do here.
     #[error("unknown bits in umask")]