feat: Add comments to generated files

docs/reference/admin/appservices.md

@@ -1,3 +1,4 @@
+<!-- This file is generated by `cargo xtask generate-docs`. Do not edit. -->
 # `!admin appservices`
 
 - Commands for managing appservices

docs/reference/admin/check.md

@@ -1,3 +1,4 @@
+<!-- This file is generated by `cargo xtask generate-docs`. Do not edit. -->
 # `!admin check`
 
 - Commands for checking integrity

docs/reference/admin/debug.md

@@ -1,3 +1,4 @@
+<!-- This file is generated by `cargo xtask generate-docs`. Do not edit. -->
 # `!admin debug`
 
 - Commands for debugging things

docs/reference/admin/federation.md

@@ -1,3 +1,4 @@
+<!-- This file is generated by `cargo xtask generate-docs`. Do not edit. -->
 # `!admin federation`
 
 - Commands for managing federation

docs/reference/admin/index.md

@@ -1,3 +1,4 @@
+<!-- This file is generated by `cargo xtask generate-docs`. Do not edit. -->
 # Admin Commands
 
 These are all the admin commands. TODO fill me out

docs/reference/admin/media.md

@@ -1,3 +1,4 @@
+<!-- This file is generated by `cargo xtask generate-docs`. Do not edit. -->
 # `!admin media`
 
 - Commands for managing media

docs/reference/admin/query.md

@@ -1,3 +1,4 @@
+<!-- This file is generated by `cargo xtask generate-docs`. Do not edit. -->
 # `!admin query`
 
 - Low-level queries for database getters and iterators

docs/reference/admin/rooms.md

@@ -1,3 +1,4 @@
+<!-- This file is generated by `cargo xtask generate-docs`. Do not edit. -->
 # `!admin rooms`
 
 - Commands for managing rooms

docs/reference/admin/server.md

@@ -1,3 +1,4 @@
+<!-- This file is generated by `cargo xtask generate-docs`. Do not edit. -->
 # `!admin server`
 
 - Commands for managing the server

docs/reference/admin/token.md

@@ -1,3 +1,4 @@
+<!-- This file is generated by `cargo xtask generate-docs`. Do not edit. -->
 # `!admin token`
 
 - Commands for managing registration tokens

docs/reference/admin/users.md

@@ -1,3 +1,4 @@
+<!-- This file is generated by `cargo xtask generate-docs`. Do not edit. -->
 # `!admin users`
 
 - Commands for managing local users

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<String> {
+        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)?;
+                }
             }
         }