From 7b159bc8c8922562bb090677ccd79e75274aafb8 Mon Sep 17 00:00:00 2001 From: Ginger Date: Mon, 12 Jan 2026 10:03:13 -0500 Subject: [PATCH] feat: Add comments to generated files --- docs/reference/admin/appservices.md | 1 + docs/reference/admin/check.md | 1 + docs/reference/admin/debug.md | 1 + docs/reference/admin/federation.md | 1 + docs/reference/admin/index.md | 1 + docs/reference/admin/media.md | 1 + docs/reference/admin/query.md | 1 + docs/reference/admin/rooms.md | 1 + docs/reference/admin/server.md | 1 + docs/reference/admin/token.md | 1 + docs/reference/admin/users.md | 1 + xtask/src/tasks/generate_docs/mod.rs | 24 ++++++++++++++++++++++-- 12 files changed, 33 insertions(+), 2 deletions(-) diff --git a/docs/reference/admin/appservices.md b/docs/reference/admin/appservices.md index 84859d3b..f0229222 100644 --- a/docs/reference/admin/appservices.md +++ b/docs/reference/admin/appservices.md @@ -1,3 +1,4 @@ + # `!admin appservices` - Commands for managing appservices diff --git a/docs/reference/admin/check.md b/docs/reference/admin/check.md index fd8ce4e7..08d4c2c1 100644 --- a/docs/reference/admin/check.md +++ b/docs/reference/admin/check.md @@ -1,3 +1,4 @@ + # `!admin check` - Commands for checking integrity diff --git a/docs/reference/admin/debug.md b/docs/reference/admin/debug.md index be3bc709..536e97e1 100644 --- a/docs/reference/admin/debug.md +++ b/docs/reference/admin/debug.md @@ -1,3 +1,4 @@ + # `!admin debug` - Commands for debugging things diff --git a/docs/reference/admin/federation.md b/docs/reference/admin/federation.md index 9f16697d..d9f40962 100644 --- a/docs/reference/admin/federation.md +++ b/docs/reference/admin/federation.md @@ -1,3 +1,4 @@ + # `!admin federation` - Commands for managing federation diff --git a/docs/reference/admin/index.md b/docs/reference/admin/index.md index b80dc723..9f724f02 100644 --- a/docs/reference/admin/index.md +++ b/docs/reference/admin/index.md @@ -1,3 +1,4 @@ + # Admin Commands These are all the admin commands. TODO fill me out diff --git a/docs/reference/admin/media.md b/docs/reference/admin/media.md index 93909809..46b10c88 100644 --- a/docs/reference/admin/media.md +++ b/docs/reference/admin/media.md @@ -1,3 +1,4 @@ + # `!admin media` - Commands for managing media diff --git a/docs/reference/admin/query.md b/docs/reference/admin/query.md index 89b5131b..87ad0347 100644 --- a/docs/reference/admin/query.md +++ b/docs/reference/admin/query.md @@ -1,3 +1,4 @@ + # `!admin query` - Low-level queries for database getters and iterators diff --git a/docs/reference/admin/rooms.md b/docs/reference/admin/rooms.md index 48656ac1..cb70eee8 100644 --- a/docs/reference/admin/rooms.md +++ b/docs/reference/admin/rooms.md @@ -1,3 +1,4 @@ + # `!admin rooms` - Commands for managing rooms diff --git a/docs/reference/admin/server.md b/docs/reference/admin/server.md index 98ee95f8..8e3aa0cb 100644 --- a/docs/reference/admin/server.md +++ b/docs/reference/admin/server.md @@ -1,3 +1,4 @@ + # `!admin server` - Commands for managing the server diff --git a/docs/reference/admin/token.md b/docs/reference/admin/token.md index af0958d6..8a4d3d44 100644 --- a/docs/reference/admin/token.md +++ b/docs/reference/admin/token.md @@ -1,3 +1,4 @@ + # `!admin token` - Commands for managing registration tokens diff --git a/docs/reference/admin/users.md b/docs/reference/admin/users.md index 8096aa48..50b8c6e3 100644 --- a/docs/reference/admin/users.md +++ b/docs/reference/admin/users.md @@ -1,3 +1,4 @@ + # `!admin users` - Commands for managing local users diff --git a/xtask/src/tasks/generate_docs/mod.rs b/xtask/src/tasks/generate_docs/mod.rs index 1df34dc4..5da1651c 100644 --- a/xtask/src/tasks/generate_docs/mod.rs +++ b/xtask/src/tasks/generate_docs/mod.rs @@ -1,6 +1,6 @@ mod admin_commands; -use std::{collections::HashMap, path::{Path, PathBuf}}; +use std::{collections::HashMap, fs::File, io::Write, path::{Path, PathBuf}}; use cargo_metadata::MetadataCommand; @@ -16,13 +16,33 @@ struct FileQueue { } impl FileQueue { + const GENERATED_HEADER: &'static str = "This file is generated by `cargo xtask generate-docs`. Do not edit."; + + /// Generate the header for the file at `path`. + fn header_for(path: &Path) -> Option { + Some(match path.extension()?.as_encoded_bytes() { + b"md" => format!("", Self::GENERATED_HEADER), + _ => return None + }) + } + + /// Write all queued files into the file tree rooted at `root`. fn write(self, root: &Path, dry_run: bool) -> std::io::Result<()> { for (path, contents) in self.queue { let path = root.join(&path); eprintln!("Writing {}", path.display()); if !dry_run { - std::fs::write(path, contents)?; + let mut file = File::create(&path)?; + + if let Some(header) = Self::header_for(&path) { + writeln!(file, "{header}")?; + } + + write!(file, "{contents}")?; + if !contents.ends_with('\n') { + writeln!(file)?; + } } }