From d6ce661923828e48701e8d5614a9b623cc8f04e6 Mon Sep 17 00:00:00 2001
From: nyash-codex <codex@nyash.local>
Date: Sat, 29 Nov 2025 09:04:28 +0900
Subject: [PATCH] docs(joinir): Phase P5 add responsibility docs to if patterns
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add responsibility documentation to if_return.rs, nested_if.rs,
and read_quoted.rs following the box-theory pattern.

Each module now has:
- One-line responsibility declaration
- Pattern example
- Generated JoinIR structure

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../join_ir/frontend/ast_lowerer/if_return.rs | 21 +++++++++++++
 .../join_ir/frontend/ast_lowerer/nested_if.rs | 21 +++++++++++++
 .../frontend/ast_lowerer/read_quoted.rs       | 30 +++++++++++++++++--
 3 files changed, 69 insertions(+), 3 deletions(-)

diff --git a/src/mir/join_ir/frontend/ast_lowerer/if_return.rs b/src/mir/join_ir/frontend/ast_lowerer/if_return.rs
index 6fabdc09..9b27dd9b 100644
--- a/src/mir/join_ir/frontend/ast_lowerer/if_return.rs
+++ b/src/mir/join_ir/frontend/ast_lowerer/if_return.rs
@@ -1,3 +1,24 @@
+//! Phase P5: If Return パターン lowering
+//!
+//! ## 責務（1行で表現）
+//! **if-then-else で異なる値を return するパターンを Select に落とす**
+//!
+//! ## パターン例
+//! ```nyash
+//! // simple pattern
+//! if cond { return 10 } else { return 20 }
+//!
+//! // local pattern
+//! if cond { x = 10 } else { x = 20 }
+//! return x
+//!
+//! // json_shape pattern
+//! if at { return v.substring(0, at) } else { return v }
+//! ```
+//!
+//! ## 生成する JoinIR 構造
+//! - 単一関数: cond 評価 → Select(cond, then_val, else_val) → Ret
+
 use super::{AstToJoinIrLowerer, BTreeMap, ExtractCtx, JoinFunction, JoinInst, JoinModule};
 
 impl AstToJoinIrLowerer {
diff --git a/src/mir/join_ir/frontend/ast_lowerer/nested_if.rs b/src/mir/join_ir/frontend/ast_lowerer/nested_if.rs
index 55997a4e..ebbb49b3 100644
--- a/src/mir/join_ir/frontend/ast_lowerer/nested_if.rs
+++ b/src/mir/join_ir/frontend/ast_lowerer/nested_if.rs
@@ -1,3 +1,24 @@
+//! Phase P5/41-4: Nested If パターン lowering
+//!
+//! ## 責務（1行で表現）
+//! **深いネスト if（3-4レベル）を NestedIfMerge 命令に落とす**
+//!
+//! ## パターン例
+//! ```nyash
+//! if cond0 {
+//!     if cond1 {
+//!         if cond2 {
+//!             x = new_value  // deepest level
+//!         }
+//!     }
+//! }
+//! // At merge point: x has PHI semantics
+//! ```
+//!
+//! ## 生成する JoinIR 構造
+//! - NestedIfMerge 命令でマルチレベル条件を表現
+//! - 各レベルの条件を accumulate して最終値を決定
+
 use super::BTreeMap;
 use super::{AstToJoinIrLowerer, ExtractCtx, JoinFunction, JoinInst, JoinModule};
 
diff --git a/src/mir/join_ir/frontend/ast_lowerer/read_quoted.rs b/src/mir/join_ir/frontend/ast_lowerer/read_quoted.rs
index c774e0d5..fe362617 100644
--- a/src/mir/join_ir/frontend/ast_lowerer/read_quoted.rs
+++ b/src/mir/join_ir/frontend/ast_lowerer/read_quoted.rs
@@ -1,12 +1,36 @@
+//! Phase P5/45: Read Quoted パターン lowering
+//!
+//! ## 責務（1行で表現）
+//! **Guard if + Loop with break + accumulator パターンを JoinIR に落とす**
+//!
+//! ## パターン例
+//! ```nyash
+//! read_quoted_from(s, pos) {
+//!     local i = pos
+//!     if s.substring(i, i+1) != "\"" { return "" }  // Guard if
+//!     i = i + 1
+//!     local out = ""
+//!     loop (i < n) {
+//!         local ch = s.substring(i, i+1)
+//!         if ch == "\"" { break }  // Found closing quote
+//!         out = out + ch
+//!         i = i + 1
+//!     }
+//!     return out
+//! }
+//! ```
+//!
+//! ## 生成する JoinIR 構造
+//! - Guard if: 早期 return で不正入力を弾く
+//! - Loop: accumulator パターンで文字列を構築
+//! - Break: 終端条件で抜ける
+
 use super::BTreeMap;
 use super::{
     AstToJoinIrLowerer, ConstValue, ExtractCtx, JoinFunction, JoinInst, JoinModule, MergePair,
 };
 
 impl AstToJoinIrLowerer {
-    // ========================================
-    // Phase 45: read_quoted_from Pattern Lowering
-    // ========================================
 
     /// Phase 45: read_quoted_from パターンの lowering
     ///