craft-update: doc comments for the functions and tests this PR touches

CodeRabbit's docstring check counted 76% of the functions this PR touches as documented, below its
80% threshold. install_at, the Linux detect, linux_location and three tests had none.

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

crates/update/src/install.rs

@@ -58,6 +58,11 @@ pub fn install(
 
 type RecordCommit<'a> = Option<&'a mut dyn FnMut(&Record) -> Result<(), String>>;
 
+/// [`install`], with `commit` called once a portable ZIP's new files are in place and its version
+/// checked, so the caller can save its record; an error from it rolls the previous copy back
+/// (Windows only; ignored elsewhere). Refuses before downloading when the app is running, the
+/// asset isn't the release's version (`bind_artifact_version`), a newer copy is installed, or the
+/// link isn't the release's own (`check_download_link`).
 #[allow(clippy::too_many_arguments)]
 pub fn install_at(
     app: &App,
@@ -2615,6 +2620,8 @@ mod tests {
         assert!(result.unwrap_err().contains("installed version 0.5.0 is newer"));
     }
 
+    /// An asset whose file name, link tag or link file name isn't the release's is refused before
+    /// the download, and so is one in another app's releases or with a foreign `SHA256SUMS.txt`.
     #[test]
     fn install_rejects_an_artifact_whose_version_is_not_the_advertised_one() {
         // The release advertises 99.0.0, but the selected artifact is an older official build

crates/update/src/release.rs

@@ -439,6 +439,8 @@ mod tests {
         }
     }
 
+    /// A link that shares the download prefix as text but climbs into another repository with `..`
+    /// or an encoded separator or dot isn't under it.
     #[test]
     fn traversal_cannot_escape_the_repository() {
         // Raw-prefix matches but the interpreted path climbs into another repository (CWE-180).
@@ -476,6 +478,8 @@ mod tests {
         assert_eq!(parse_github_release_list("[]", REPO, false).unwrap(), None);
     }
 
+    /// `SHA256SUMS.txt` lines, the tag in a `releases/latest` redirect, and the release built from
+    /// both; malformed lines, traversing names and `.`/`..` tags are dropped.
     #[test]
     fn reads_checksums_and_redirects() {
         let sums = parse_sha256sums(&format!("{HASH}  photocraft-0.5.0-macos-universal.dmg\n{HASH} *b.zip\nnot a line\n{HASH}  ../escape\n"));

crates/update/src/self_update.rs

@@ -214,6 +214,9 @@ fn msi_install_dir(app: &App) -> Option<PathBuf> {
     (!dir.is_empty()).then(|| PathBuf::from(dir))
 }
 
+/// How the running copy at `exe` was installed on Linux, or `None` when it isn't this app's to
+/// update: a Flatpak bundle installed per user, an AppImage, the deb/rpm/Arch package at
+/// `/usr/bin/<id>`, or a standalone copy outside the package managers' folders ([`linux_location`]).
 #[cfg(target_os = "linux")]
 fn detect(app: &App, exe: &Path) -> Option<Install> {
     if process::in_sandbox() {
@@ -263,6 +266,7 @@ enum LinuxLocation {
     Elsewhere,
 }
 
+/// Which [`LinuxLocation`] `exe` is in, from its path alone.
 #[cfg_attr(not(target_os = "linux"), allow(dead_code))]
 fn linux_location(app: &App, exe: &Path) -> LinuxLocation {
     if exe == Path::new("/usr/bin").join(app.id) {