Doc comments on ipx-feed's and ipx-directory's public items (#354)

The style guide asks for doc comments on a library's public API. Every
type, function, constant and static the two libraries export now has
one, saying what it is for or what it does that its name does not:
fetch follows redirects itself so credentials stay on the feed's host,
Config::parse refuses repeated token names, Store::due_one is the
admin's Refresh. Fields and variants whose names say it all have none,
as the guide allows.

category_path's comment had slid above categories(), which then had
two; each has its own again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

crates/directory/src/config.rs

@@ -6,9 +6,11 @@ use anyhow::{Context, Result, bail};
 use serde::Deserialize;
 use std::path::Path;
 
+/// `directory.toml`. See docs/directory.md.
 #[derive(Debug, Clone, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct Config {
+    /// Where the API and the public pages listen.
     #[serde(default = "default_bind")]
     pub bind: String,
     /// The environment variable holding the database URL, so the file holds no secret.
@@ -39,6 +41,7 @@ fn default_database_url_env() -> String {
     "DIRECTORY_DATABASE_URL".into()
 }
 
+/// A token as `directory.toml` lists it: a name, what it may do, and only the token's hash.
 #[derive(Debug, Clone, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct TokenCfg {
@@ -74,11 +77,14 @@ pub struct Token {
 }
 
 impl Config {
+    /// Reads and checks `path`; see `parse`.
     pub fn load(path: &Path) -> Result<Self> {
         let text = std::fs::read_to_string(path).with_context(|| format!("reading {}", path.display()))?;
         Self::parse(&text).with_context(|| format!("in {}", path.display()))
     }
 
+    /// Reads a config, refusing tokens with empty or repeated names, which would file two
+    /// instances' snapshots together.
     pub fn parse(text: &str) -> Result<Self> {
         let cfg: Config = toml::from_str(text)?;
         let mut seen = std::collections::HashSet::new();

crates/directory/src/lib.rs

@@ -63,7 +63,9 @@ pub struct Item {
     pub guid: String,
     pub title: Option<String>,
     pub link: Option<String>,
+    /// Unix seconds.
     pub published: Option<i64>,
+    /// Seconds.
     pub duration: Option<i64>,
     /// As the feed sent it, unsanitized.
     pub description: Option<String>,
@@ -80,6 +82,7 @@ pub struct SnapshotEntry {
     pub category: Option<String>,
 }
 
+/// What became of a snapshot's entries.
 #[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
 pub struct SnapshotResult {
     pub accepted: usize,
@@ -91,6 +94,7 @@ pub struct SnapshotResult {
     pub refused_invalid: usize,
 }
 
+/// Who a token belongs to and what it may do: `/v1/me`'s answer.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Me {
     pub name: String,
@@ -105,11 +109,13 @@ pub struct Instance {
     pub subscribers: i64,
 }
 
+/// A feed an admin removed from the directory, which snapshots may not bring back.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Blocked {
     pub id: String,
     pub url: Option<String>,
     pub title: Option<String>,
+    /// When it was blocked, Unix seconds.
     pub at: i64,
 }
 
@@ -121,6 +127,8 @@ pub const MAX_SNAPSHOT: usize = 20_000;
 /// to a feed fetches it itself anyway: every six hours was 3.9 GB of feeds a day (#243).
 pub const REFRESH_EVERY: i64 = 12 * 3600;
 
+/// The running directory: its database, the tokens it accepts and the client its refresher
+/// fetches feeds with.
 pub struct Directory {
     pub store: Store,
     tokens: RwLock<Vec<Token>>,
@@ -134,9 +142,12 @@ pub struct Directory {
 /// How long the public pages show the same copy of the list.
 const PAGES_LIST_FOR: Duration = Duration::from_secs(60);
 
+/// The directory as every handler and task holds it.
 pub type Shared = Arc<Directory>;
 
 impl Directory {
+    /// A directory on `store`, accepting `tokens`, whose refresher may reach the internal
+    /// addresses `fetch_internal` lists and no others.
     pub fn new(
         store: Store,
         tokens: Vec<Token>,
@@ -288,6 +299,7 @@ pub async fn reloader(dir: Shared, path: std::path::PathBuf) {
     }
 }
 
+/// Every route: the API under `/v1`, behind a token, and the public pages.
 pub fn router(dir: Shared) -> Router {
     let v1 = Router::new()
         .route("/v1/me", get(me))

crates/directory/src/store.rs

@@ -16,6 +16,7 @@ const FLAG_AFTER_SECS: i64 = 24 * 3600;
 /// The most subscribers one instance may say a feed has.
 pub const MAX_SUBSCRIBERS: i64 = 1_000_000;
 
+/// The directory's database: feeds, snapshots, blocks and when each sync ran.
 pub struct Store {
     db: DatabaseConnection,
 }
@@ -30,11 +31,15 @@ pub struct Due {
 
 /// What a fetch found, to be stored.
 pub enum Refreshed {
+    /// Unchanged since the last fetch.
     NotModified,
+    /// Read anew, with the validators to send next time.
     Feed { parsed: ipx_feed::ParsedFeed, etag: Option<String>, last_modified: Option<String> },
+    /// The fetch failed, and why, in words.
     Failed(String),
 }
 
+/// Unix seconds now.
 #[must_use]
 pub fn now() -> i64 {
     std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map_or(0, |d| d.as_secs() as i64)
@@ -184,6 +189,7 @@ impl Store {
         })
     }
 
+    /// Records when the sync `name` (Apple's charts) last ran.
     pub async fn set_synced(&self, name: &str, at: i64) -> Result<()> {
         self.exec(
             "INSERT INTO syncs (name, at) VALUES ($1, $2) ON CONFLICT (name) DO UPDATE SET at = excluded.at",
@@ -193,6 +199,7 @@ impl Store {
         Ok(())
     }
 
+    /// Whether the database answers, for the healthcheck.
     pub async fn ping(&self) -> Result<()> {
         self.rows("SELECT 1", vec![]).await?;
         Ok(())
@@ -377,6 +384,7 @@ impl Store {
         Ok(self.exec("DELETE FROM blocked WHERE id = $1", vec![id.into()]).await? > 0)
     }
 
+    /// Each instance that has sent a snapshot, with how many feeds and people it counted.
     pub async fn instances(&self) -> Result<Vec<Instance>> {
         // Postgres sums a BIGINT as NUMERIC, which does not read as an i64.
         self.rows(
@@ -396,6 +404,7 @@ impl Store {
         .collect()
     }
 
+    /// The feeds an admin has blocked.
     pub async fn blocked(&self) -> Result<Vec<Blocked>> {
         self.rows("SELECT id, url, title, at FROM blocked ORDER BY at DESC, id", vec![])
             .await?
@@ -432,6 +441,7 @@ impl Store {
         .collect()
     }
 
+    /// One feed, due or not, for an admin's Refresh.
     pub async fn due_one(&self, id: &str) -> Result<Option<Due>> {
         self.rows("SELECT id, url, etag, last_modified FROM feeds WHERE id = $1", vec![id.into()])
             .await?
@@ -447,6 +457,7 @@ impl Store {
             .transpose()
     }
 
+    /// Stores what a fetch of feed `id` found, and when.
     pub async fn save(&self, id: &str, got: Refreshed) -> Result<()> {
         let t = now();
         match got {