doc: minor enhancements

pageserver/src/tenant/timeline/detach_ancestor.rs

@@ -150,6 +150,8 @@ pub(super) async fn prepare(
             .values()
             .filter(|tl| matches!(tl.ancestor_timeline.as_ref(), Some(ancestor) if Arc::ptr_eq(ancestor, detached)))
             .map(|tl| (tl.ancestor_lsn, tl.clone()))
+            // Collect to avoid lock taking order problem with Tenant::timelines and
+            // Timeline::remote_client
             .collect::<Vec<_>>();
 
         let mut any_shutdown = false;

storage_controller/src/service.rs

@@ -2858,7 +2858,7 @@ impl Service {
                         Error::ApiError(StatusCode::BAD_REQUEST, msg) => {
                             ApiError::BadRequest(anyhow::anyhow!("{node}: {msg}"))
                         }
-                        // rest can be mapped
+                        // rest can be mapped as usual
                         other => passthrough_api_error(&node, other),
                     }
                 })