rustdoc comment for the (very limited) public API of the crate.

This silences some `-Wclippy::pedantic` warning, and it's just a good thing to do.

I've made the choice to have the docs comment face programmers, and to provide `hi --help` and `hi -h` content via Clap attributes instead of inferring it from the docs comment.

Internal (private) "rustdoc" comments have been converted to regular comments until I learn how to write better rustdoc.

1 files changed, 53 insertions, 3 deletions

diff --git a/src/cli.rs b/src/cli.rs
index 729a791..b147f7d 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -1,3 +1,8 @@
+//! The `hi` command-line interface.
+//!
+//! This module supports running `hi` as a freestanding program, via the
+//! [`Args`] struct.
+
 use std::io;
 
 use axum::{middleware, Router};
@@ -7,22 +12,62 @@ use tokio::net;
 
 use crate::{app::App, channel, clock, events, login, repo::pool};
 
-pub type Result<T> = std::result::Result<T, Error>;
-
+/// Command-line entry point for running the `hi` server.
+///
+/// This is intended to be used as a Clap [Parser], to capture command-line
+/// arguments for the `hi` server:
+///
+/// ```no_run
+/// # use hi::cli::Error;
+/// #
+/// # #[tokio::main]
+/// # async fn main() -> Result<(), Error> {
+/// use clap::Parser;
+/// use hi::cli::Args;
+///
+/// let args = Args::parse();
+/// args.run().await?;
+/// #   Ok(())
+/// # }
+/// ```
 #[derive(Parser)]
+#[command(
+    about = "Run the `hi` server.",
+    long_about = r#"Run the `hi` server.
+
+The database at `--database-url` will be created, or upgraded, automatically."#
+)]
 pub struct Args {
+    /// The network address `hi` should listen on
     #[arg(short, long, env, default_value = "localhost")]
     address: String,
 
+    /// The network port `hi` should listen on
     #[arg(short, long, env, default_value_t = 64209)]
     port: u16,
 
+    /// Sqlite URL or path for the `hi` database
     #[arg(short, long, env, default_value = "sqlite://.hi")]
     database_url: String,
 }
 
 impl Args {
-    pub async fn run(self) -> Result<()> {
+    /// Runs the `hi` server, using the parsed configuation in `self`.
+    ///
+    /// This will perform the following tasks:
+    ///
+    /// * Migrate the `hi` database (at `--database-url`).
+    /// * Start an HTTP server (on the interface and port controlled by
+    ///   `--address` and `--port`).
+    /// * Print a status message.
+    /// * Wait for that server to shut down.
+    ///
+    /// # Errors
+    ///
+    /// Will return `Err` if the server is unable to start, or terminates
+    /// prematurely. The specific [`Error`] variant will expose the cause
+    /// of the failure.
+    pub async fn run(self) -> Result<(), Error> {
         let pool = self.pool().await?;
 
         let app = App::from(pool).await?;
@@ -66,10 +111,15 @@ 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`].
     IoError(#[from] io::Error),
+    /// Failure due to a database error. See [`sqlx::Error`].
     DatabaseError(#[from] sqlx::Error),
+    /// Failure due to a database migration error. See
+    /// [`sqlx::migrate::MigrateError`].
     MigrateError(#[from] sqlx::migrate::MigrateError),
 }