docs: Improve core documentation

[takeshishimada]

Summary

Comprehensive documentation improvements for core Flow types (Feature, ActionHandler) based on code review feedback. All changes are documentation-only with one refactoring to improve API discoverability.

Changes

1. Add @observable requirement warning to Feature protocol

• File: Feature.swift
• Change: Add explicit warning that State must use @Observable macro
• Rationale: Type system cannot enforce this requirement, but forgetting it causes SwiftUI views to not update automatically

2. Clarify state parameter in .run closure examples

• File: Feature.swift
• Change: Add inline comments and documentation note explaining state parameter semantics
• Rationale: Both outer and inner state parameters refer to same instance (reference type), which may be confusing without clarification

3. Re-export ActionExecution typealias in ActionHandler

• File: ActionHandler.swift, ActionProcessor.swift
• Change: Move ActionExecution typealias definition to ActionHandler.swift with comprehensive documentation
• Rationale: Improves discoverability - users working with ActionHandler now have direct access to the type definition

4. Document Feature.handle() call semantics

• File: Feature.swift
• Change: Add note explaining handle() is called once during Store initialization
• Rationale: Clarifies lifecycle management - prevents confusion about when/how often to call handle()

5. Fill ActionHandler documentation gaps

• File: ActionHandler.swift
• Changes:
  • onError: Clarify multiple calls replace previous handler + add example
  • transform: Add detailed logging example showing practical use case
  • use: Document middleware execution order (registration order) + add example
• Rationale: These methods had minimal documentation, making them hard to use correctly

Testing

• ✅ All 299 tests pass
• ✅ SwiftLint clean (no violations)

Impact

• Breaking Changes: None
• API Changes: ActionExecution now publicly exported from ActionHandler.swift (improvement)
• Documentation: Significantly improved clarity for core types

🤖 Generated with Claude Code