Fix #5526: document the functions the link-status selection touches

Doc comments for the Select add-on commands, the Select by Link Status
dialog body, the Links panel menu and the test helpers (review: docstring
coverage).

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

crates/engine/src/cmd/addons/select.rs

@@ -25,6 +25,7 @@ pub const RELATIONS: [&str; 3] = ["overlap", "inside", "outside"];
 /// in the document, a file not found, a file changed since it was read.
 pub const LINK_STATUSES: [&str; 4] = ["linked", "embedded", "missing", "modified"];
 
+/// The add-on's commands: Select by Artboards and Select by Link Status.
 pub fn specs() -> Vec<CommandSpec> {
     vec![
         cmd!(
@@ -48,6 +49,8 @@ pub fn specs() -> Vec<CommandSpec> {
     ]
 }
 
+/// `addon.select.byArtboards`: select the objects Select All takes that overlap, lie inside or lie
+/// outside the chosen artboards.
 fn by_artboards(s: &mut Session, p: &Value) -> Result<Value> {
     const C: &str = "addon.select.byArtboards";
     let relation = text_param(p, "relation", C)?.unwrap_or("overlap");
@@ -151,6 +154,9 @@ fn skip_reason(st: &DocState, locks: &LockedArtboards, id: NodeId) -> Option<&'s
     })
 }
 
+/// `addon.select.byLinkStatus`: select the images and placed documents whose link has one of the
+/// statuses asked for (among `ids` when given), replacing the selection or adding to it, and list
+/// those left out with the reason ([`skip_reason`]).
 fn by_link_status(s: &mut Session, p: &Value) -> Result<Value> {
     const C: &str = "addon.select.byLinkStatus";
     let wanted = link_statuses(p, C)?;

crates/engine/src/cmd/addons/select/tests.rs

@@ -150,6 +150,8 @@ mod by_link_status {
         _dir: Folder,
     }
 
+    /// [`Links`] in a fresh folder named after `name`: the files placed, then one changed and two
+    /// removed.
     fn links(name: &str) -> Links {
         let dir = Folder::new(name);
         let (a, b, c, e, d) = (dir.file("ok.png"), dir.file("changes.png"), dir.file("goes.png"), dir.file("kept.png"), dir.file("page.vectorcraft"));
@@ -168,19 +170,23 @@ mod by_link_status {
         Links { s, ok, modified, missing, embedded, document, _dir: dir }
     }
 
+    /// Run the command with `p`, which must succeed.
     fn run(s: &mut Session, p: Value) -> Value {
         s.execute(C, &p).unwrap_or_else(|e| panic!("{p}: {e}"))
     }
 
+    /// `v` sorted.
     fn sorted(mut v: Vec<NodeId>) -> Vec<NodeId> {
         v.sort();
         v
     }
 
+    /// The selected objects, sorted.
     fn selection(s: &Session) -> Vec<NodeId> {
         sorted(s.doc().unwrap().selection.objects.clone())
     }
 
+    /// The ids of a JSON list, sorted.
     fn ids(v: &Value) -> Vec<NodeId> {
         sorted(v.as_array().unwrap().iter().map(|i| NodeId(i.as_u64().unwrap())).collect())
     }