docs(former): Add purpose and coverage to basic unnamed enum tests

Author: Wandalen

module/core/former/plan.md

@@ -259,7 +259,21 @@ This section shows an example of the documentation comments that will be added t
 ---
 **Phase 2: Unnamed/Tuple Variant Tests (`enum_unnamed_tests`)**
 
-*   [⚫] **Increment 8:** Document `basic_*` files
+*   [✅] **Increment 8:** Document `basic_*` files
+    *   Detailed Plan Step 1: Read the content of the target files to perform pre-analysis.
+    *   Detailed Plan Step 2: Perform pre-analysis based on file content and plan rules.
+    *   Detailed Plan Step 3: Draft the `//!` comments (Purpose, Coverage, Test Relevance/Acceptance Criteria) for each target file based on pre-analysis and plan requirements.
+    *   Detailed Plan Step 4: Apply the drafted comments to the target files using `write_to_file`.
+    *   Detailed Plan Step 5: Request user to run verification command.
+    *   Pre-Analysis:
+        *   Identified enum variant structures in target file(s): Single-field tuple variants (`Break(Break)`, `Run(Run)`).
+        *   Key attributes present: `#[derive(Former)]`, `#[standalone_constructors]` on the enum; `#[subform_scalar]` on the `Break` variant.
+        *   Relevant "Expected Enum Former Behavior Rule IDs": 3d, 2d, 4a, 4b. Rule 1d is not applicable to this test case.
+        *   Brief summary of how test functions appear to exercise these rules: `basic_only_test.rs` contains tests that call the static methods (`FunctionStep::r#break()`, `FunctionStep::run()`) and the standalone constructor (`FunctionStep::break_variant()`). These tests then use the returned subformers to set fields and call `.form()`, asserting the final enum instance matches the expected value.
+    *   Crucial Design Rules: Comments and Documentation, Comments: Spaces, Comments: Focus on Rationale, Preserve Existing Tasks, Comments: Add Tasks and Label Simplifications, Comments: Annotate Addressed Tasks, Structuring: Proc Macro Development Workflow.
+    *   Relevant Behavior Rules: Rule 3d (Tuple + Default -> Subform), Rule 2d (Tuple + `#[subform_scalar]` -> InnerFormer), Rule 4a (#[standalone_constructors]), Rule 4b (Option 2 Logic).
+    *   Verification Strategy: After comments are added, request user to run `cargo check --package former --tests`. The code must compile without errors.
+    *   Test Matrix: N/A
     *   Enum Aspect Focus: Unnamed/Tuple (basic single-field subform)
     *   Target File(s):
         *   `module/core/former/tests/inc/enum_unnamed_tests/basic_derive.rs`
@@ -413,7 +427,7 @@ This section shows an example of the documentation comments that will be added t
             *   What is the nature of the primary assertion (e.g., "Asserts the `got` instance (produced by the former) is equal to an `expected` instance (manually constructed to represent the correct state).", "Asserts that a subformer is returned and can be used to set inner fields.", "Asserts that a compile-time error occurs for an invalid attribute combination using `trybuild`.").
         *   **For `_derive.rs` files:** Mention that it relies on `#[derive(Former)]` for code generation and typically includes shared test logic via `include!("...")`.
         *   **For `_manual.rs` files:** Mention that it contains a hand-written former implementation and includes shared test logic via `include!("...")`.
-        *   **For `compile_fail/*.rs` files:** The file contains code that intentionally uses an attribute or enum structure in a way that violates a documented behavior rule (e.e., `#[subform_scalar]` on a unit variant). The test is accepted if `trybuild` confirms this results in a compilation error, thereby validating the macro's error reporting for this specific invalid scenario."
+        *   **For `compile_fail/*.rs` files:** The file contains code that intentionally uses an attribute or enum structure in a way that violates a documented behavior rule (i.e., `#[subform_scalar]` on a unit variant). The test is accepted if `trybuild` confirms this results in a compilation error, thereby validating the macro's error reporting for this specific invalid scenario."
 *   **Comment Style:** All added `//!` comments should be clear, concise, grammatically correct, and follow Rust documentation comment conventions. Use Markdown for lists or emphasis if it enhances readability. Aim for reasonable line lengths.
 *   **Pre-Analysis Output:** Before proposing comments for an increment, the AI must provide its pre-analysis findings for the targeted file(s) as specified in the "Increment Template".
 *   **Incremental Processing:** Modify files one increment at a time, following the "Increment Template."
@@ -438,3 +452,4 @@ This section shows an example of the documentation comments that will be added t
 *   **[2025-05-10/Inc 5] Note:** Started detailed planning for Increment 5: Document `standalone_constructor_unit_*` files. Pre-analysis complete. Proceeding to draft and apply comments. Successfully applied comments and verified compilation with `cargo check --package former --tests`. Increment 5 complete.
 *   **[2025-05-10/Inc 6] Note:** Started detailed planning for Increment 6: Document `standalone_constructor_args_unit_*` files. Pre-analysis complete. Proceeding to draft and apply comments. Successfully applied comments and verified compilation with `cargo check --package former --tests`. Increment 6 complete.
 *   **[2025-05-10/Inc 7] Note:** Started detailed planning for Increment 7: Document `compile_fail/unit_subform_scalar_error.rs`. Pre-analysis complete. Proceeding to draft and apply comments. Successfully applied comments and verified compilation with `cargo check --package former --tests`. Increment 7 complete.
+*   **[2025-05-10/Inc 8] Note:** Started detailed planning for Increment 8: Document `basic_*` files. Pre-analysis complete. Proceeding to draft and apply comments. Successfully applied comments and verified compilation with `cargo check --package former --tests`. Increment 8 complete.

module/core/former/tests/inc/enum_unnamed_tests/basic_derive.rs

@@ -1,11 +1,10 @@
 //! Purpose: Tests the `#[derive(Former)]` macro's generation of constructors for unnamed (tuple)
-//! variants, including with `#[subform_scalar]` and `#[standalone_constructors]`. This file
-//! focuses on verifying the derive-based implementation.
+//! variants that return subformers, including with `#[subform_scalar]` and `#[standalone_constructors]`.
+//! This file focuses on verifying the derive-based implementation.
 //!
 //! Coverage:
-//! - Rule 3d (Tuple + Default -> Subform): Verifies `FunctionStep::run() -> RunFormer`.
-//! - Rule 1d (Tuple + `#[scalar]` -> Scalar): Not explicitly tested in this file's enum definition.
-//! - Rule 2d (Tuple + `#[subform_scalar]` -> InnerFormer): Verifies `FunctionStep::r#break() -> BreakFormer`.
+//! - Rule 3d (Tuple + Default -> Subform): Tests static method `FunctionStep::run()`.
+//! - Rule 2d (Tuple + `#[subform_scalar]` -> InnerFormer): Tests static method `FunctionStep::r#break()`.
 //! - Rule 4a (#[standalone_constructors]): Verifies generation of top-level constructor functions.
 //! - Rule 4b (Option 2 Logic): Implicitly covered by the standalone constructor returning a subformer.
 //!
@@ -16,7 +15,6 @@
 //!   standalone constructor (`FunctionStep::break_variant()`) defined in `basic_only_test.rs`.
 //! - Asserts that these constructors return the expected subformers and that using the subformers
 //!   to set fields and call `.form()` results in the correct `FunctionStep` enum instances.
-// File: module/core/former/tests/inc/former_enum_tests/basic_derive.rs
 
 use super::*;
 

module/core/former/tests/inc/enum_unnamed_tests/basic_manual.rs

@@ -4,7 +4,6 @@
 //!
 //! Coverage:
 //! - Rule 3d (Tuple + Default -> Subform): Manual implementation of static method `FunctionStep::run()`.
-//! - Rule 1d (Tuple + `#[scalar]` -> Scalar): Not applicable to the variants in this file.
 //! - Rule 2d (Tuple + `#[subform_scalar]` -> InnerFormer): Manual implementation of static method `FunctionStep::r#break()`.
 //! - Rule 4a (#[standalone_constructors]): Manual implementation of the standalone subformer starter `break_variant()`.
 //! - Rule 4b (Option 2 Logic): Manual implementation of `FormingEnd` for the variant end types.
@@ -16,7 +15,6 @@
 //! - Manually implements `FormingEnd` for the end types associated with the variant subformers.
 //! - This file is included by `basic_only_test.rs` to provide the manual implementations that
 //!   the shared tests compare against.
-// File: module/core/former/tests/inc/former_enum_tests/basic_derive.rs
 
 use super::*;
 use former::StoragePreform;

module/core/former/tests/inc/enum_unnamed_tests/basic_only_test.rs

@@ -1,21 +1,22 @@
-// Purpose: Provides shared test assertions and logic for verifying the constructors generated
-// by `#[derive(Former)]` for enums with unnamed (tuple) variants that return subformers.
-// This file is included by both `basic_derive.rs` and `basic_manual.rs`.
-//
-// Coverage:
-// - Rule 3d (Tuple + Default -> Subform): Tests static method `FunctionStep::run()`.
-// - Rule 2d (Tuple + `#[subform_scalar]` -> InnerFormer): Tests static method `FunctionStep::r#break()`.
-// - Rule 4a (#[standalone_constructors]): Tests the standalone subformer starter `FunctionStep::break_variant()`.
-// - Rule 4b (Option 2 Logic): Tests the use of subformer methods and `.form()`.
-//
-// Test Relevance/Acceptance Criteria:
-// - Defines test functions (`build_break_variant_static`, `build_run_variant_static`, `standalone_break_variant`)
-//   that invoke constructors provided by the including file (either derived or manual).
-// - These constructors return subformers (`BreakFormer`, `RunFormer`).
-// - The tests use the subformer methods (`.condition()`, `.command()`) to set fields and call `.form()`
-//   to finalize the construction.
-// - Asserts that the resulting `FunctionStep` enum instances are equal to the expected variants
-//   (`FunctionStep::Break(...)`, `FunctionStep::Run(...)`).
+//! Purpose: Provides shared test assertions and logic for verifying the constructors generated
+//! by `#[derive(Former)]` for enums with unnamed (tuple) variants that return subformers.
+//! This file is included by both `basic_derive.rs` and `basic_manual.rs`.
+//!
+//! Coverage:
+//! - Rule 3d (Tuple + Default -> Subform): Tests static method `FunctionStep::run()`.
+//! - Rule 2d (Tuple + `#[subform_scalar]` -> InnerFormer): Tests static method `FunctionStep::r#break()`.
+//! - Rule 4a (#[standalone_constructors]): Tests the standalone subformer starter `FunctionStep::break_variant()`.
+//! - Rule 4b (Option 2 Logic): Tests the use of subformer methods and `.form()`.
+//!
+//! Test Relevance/Acceptance Criteria:
+//! - Defines test functions (`build_break_variant_static`, `build_run_variant_static`, `standalone_break_variant`)
+//!   that invoke constructors provided by the including file (either derived or manual).
+//! - These constructors return subformers (`BreakFormer`, `RunFormer`).
+//! - The tests use the subformer methods (`.condition()`, `.command()`) to set fields and call `.form()`
+//!   to finalize the construction.
+//! - Asserts that the resulting `FunctionStep` enum instances are equal to the expected variants
+//!   (`FunctionStep::Break(...)`, `FunctionStep::Run(...)`).
+
 #[ test ]
 fn build_break_variant_static() // Test name kept for clarity, could be renamed
 {