Restore rationale comments dropped by the Clippy refactors

crates/gpu/src/fx.rs

@@ -363,6 +363,8 @@ fn satin_program(b: &mut B, s: &photocraft_doc::Satin) -> usize {
 fn stroke_program(b: &mut B, st: &photocraft_doc::StrokeFx, vector_shape: bool) -> usize {
     let (in_w, out_w) = stroke_widths(st);
     if out_w > 0.0 {
+        // Narrow strokes keep the fitted chamfer, wide ones the exact transform (#3646);
+        // the CPU picks the same field by the same width (`stroke_outside_exact`).
         let kind = match (vector_shape, photocraft_compose::effects::stroke_outside_exact(out_w)) {
             (true, true) => FieldKind::StrokeOutsideVector,
             (true, false) => FieldKind::StrokeOutsideVectorChamfer,

crates/io/src/psd_export/estimate.rs

@@ -3,8 +3,10 @@ use photocraft_psd::{PsdFile, Version, file::LayerInfoPlacement};
 
 /// The signature a kept tagged block is written with. `8B64` exists only in PSB files: a PSD
 /// with an `8B64` block (kept from a PSB source, e.g. its global `FMsk` or `cinf`) is refused by
-/// Photoshop as "not compatible with this version". The other way round, a PSB block with an
-/// 8-byte length is `8B64`, as Photoshop writes it.
+/// Photoshop as "not compatible with this version" (measured in Photoshop 27.11). The other way
+/// round, a PSB block with an 8-byte length is `8B64`, as Photoshop writes it: an `8BIM` `lnk2`,
+/// `pths` or `cinf` (kept from a PSD source, whose lengths the PSB widens) makes Photoshop read
+/// the length as 4 bytes and refuse the whole file (#7937).
 pub(crate) fn block_signature(sig: [u8; 4], key: [u8; 4], version: Version) -> [u8; 4] {
     match version {
         Version::Psd if sig == *b"8B64" => *b"8BIM",
@@ -26,7 +28,9 @@ pub(crate) fn psd_version(doc: &Document, force_psb: bool) -> Version {
     if force_psb || exceeds_dimensions { Version::Psb } else { Version::Psd }
 }
 
-/// Promote files that exceed the PSD limit, accounting for the preview appended by the save.
+/// Promote files that exceed the PSD limit, accounting for the preview appended by the save
+/// (#212, #5285). The decision is made on the exact length of the file as it will be written,
+/// not on the raw pixel size: RLE usually packs the channels far below it.
 pub(crate) fn fit_psd_size(file: &mut PsdFile, limit: u64) -> Option<String> {
     if file.written_version() == Version::Psb {
         return None;

crates/io/src/psd_import.rs

@@ -1110,6 +1110,9 @@ fn read_initial_metadata(file: &PsdFile, global: &[PsdGlobalBlock], doc: &mut Do
     }
     crate::guides_map::apply_colors(doc);
     doc.metadata.psd_global_blocks.extend(global.iter().cloned());
+    // A 16/32-bit file whose layer block can't be parsed would otherwise open as a flattened
+    // file without a word (#2700). The raw block is kept, but a PSD save writes the document's
+    // own layers in its place (see `psd_export`).
     let mut damaged = false;
     if let Some((block, error)) = file.unreadable_layer_block() {
         damaged = true;

crates/text/src/layout/lines.rs

@@ -380,6 +380,9 @@ impl Para<'_> {
         // its descenders hang below the bottom edge (#1317: three 35 pt lines in a
         // 91.3 pt box, the last baseline at 88). Requiring the descent to fit dropped
         // that line.
+        // Photoshop keeps a horizontal line whose baseline is inside the box and lets its
+        // descenders hang below the bottom edge (#1317: three 35 pt lines in a 91.3 pt box, the
+        // last baseline at 88). Requiring the descent to fit dropped that line.
         let overflow = if env.vertical { baseline + descent > -box_x + 0.5 } else { baseline > box_y + box_h + 0.5 };
         if env.is_box && overflow {
             return None;

crates/ui-egui/src/menus/invoke.rs

@@ -184,6 +184,8 @@ fn invoke_shell_commands(app: &mut PhotocraftApp, ctx: &egui::Context, id: &str,
 
 fn invoke_file_commands(app: &mut PhotocraftApp, ctx: &egui::Context, id: &str, params: &Value) -> Result<Option<Value>, String> {
     let result = match id {
+        // ⌘↩ / Ctrl+Enter (#306): load the path selected in the Paths panel (or the one being
+        // drawn) as a selection.
         "path.toSelection" if params.get("name").is_none() => crate::vector_ui::path_to_selection(app, params.clone()),
         // Layer › Rename Layer from a menu starts in-place renaming in the Layers panel.
         "layer.renameLayer" if params.get("name").is_none() => {
@@ -468,6 +470,7 @@ fn invoke_export_command(app: &mut PhotocraftApp, id: &str, params: &Value) -> R
         layer if matches!(layer, "layer.exportAs" | "layer.quickExportAsPng") && params.as_object().is_none_or(|object| object.is_empty()) => {
             let selected = app.session.active().and_then(|document| document.active_layer).ok_or("no active layer")?;
             if layer == "layer.exportAs" {
+                // Several layers (artboards, say) selected: one file each (#3629).
                 let layers = app.session.active().map(|document| document.selected_layers()).unwrap_or_default();
                 if layers.len() > 1 {
                     Some(Ok(json!({"dialog": crate::export_dialog::open_layers(app, &layers)?})))
@@ -519,6 +522,7 @@ fn invoke_type_command(app: &mut PhotocraftApp, ctx: &egui::Context, id: &str, p
             }
             Ok(Value::Null)
         })()),
+        // While editing type, the clipboard rows and Select > All work on the text (#1355, #2893).
         "edit.cut" if app.ui.text_edit.is_some() => {
             crate::type_tool::cut_selection(app, ctx);
             Some(Ok(Value::Null))
@@ -690,6 +694,8 @@ fn invoke_window_command(app: &mut PhotocraftApp, ctx: &egui::Context, id: &str)
 
 fn toggle_panels(app: &mut PhotocraftApp) -> Result<Value, String> {
     if app.ui.view.hides_chrome() {
+        // Full Screen Mode: Tab only shows or hides the chrome for now (#6760); the panels'
+        // own state, `hidden_by_tab` included, stays as it was before entering.
         app.ui.panels.full_screen_chrome = !app.ui.panels.full_screen_chrome;
         return Ok(Value::Null);
     }
@@ -709,6 +715,7 @@ fn toggle_panels(app: &mut PhotocraftApp) -> Result<Value, String> {
 
 fn toggle_panel(app: &mut PhotocraftApp, id: &str) -> Result<Value, String> {
     let key = &id["window.toggle.".len()..];
+    // A shown but collapsed dock group is expanded rather than hidden (#129).
     if let Some(group) = crate::dock::Group::from_key(key).filter(|group| group.shown(&app.ui.panels) && app.ui.dock.is_collapsed(*group)) {
         crate::dock::reveal(app, group);
         return Ok(Value::Null);

crates/ui-egui/src/panels/actions.rs

@@ -865,6 +865,7 @@ fn action_context_menu(app: &mut PhotocraftApp, response: &egui::Response, index
     egui::Popup::context_menu(response).close_behavior(egui::PopupCloseBehavior::CloseOnClickOutside).show(|ui| {
         ui.label(tl!("Keyboard Shortcuts"));
         let current = app.session.prefs().shortcuts.get(&shortcut_id(name)).cloned().unwrap_or_default();
+        // Photoshop's Action Options: a function key, with Shift and Command (#7646).
         let (key, mut shift, mut command) = photocraft_engine::atn_cmds::parse_function_key(&current).unwrap_or((0, false, false));
         for number in std::iter::once(0).chain(1..=12) {
             let label = if number == 0 { tl!("None").to_string() } else { format!("F{number}") };

crates/ui-egui/src/panels/channels_panel.rs

@@ -118,6 +118,8 @@ fn handle_channel_row_click(ui: &egui::Ui, row: &mut RowInteractions<'_>) {
 }
 
 fn handle_channel_row_double_click(ui: &mut egui::Ui, row: &mut RowInteractions<'_>, rename_id: egui::Id) {
+    // Like Photoshop: double-clicking the thumbnail opens Channel Options (where an alpha
+    // channel becomes a spot channel, #3761), double-clicking the name renames it.
     let on_thumb = row.response.interact_pointer_pos().is_some_and(|p| p.x < row.cell.right() + 4.0);
     match row.row {
         Row::QuickMask if row.response.double_clicked() => row.actions.push(("ui.channelOptions".into(), json!("quickMask"))),

crates/ui-egui/src/tools/type_tool/keys.rs

@@ -248,6 +248,8 @@ fn handle_pressed_key(
         Key::Enter if modifiers.command => commit_with(app, *modifiers),
         Key::Enter => insert(app, "\n"),
         Key::Tab if !modifiers.command && !modifiers.alt && !modifiers.shift => {
+            // egui queues focus navigation before this handler runs; consuming the
+            // key alone would let the menu bar take focus after the first tab (#8889).
             ctx.memory_mut(|memory| memory.move_focus(egui::FocusDirection::None));
             insert(app, "\t");
         }