Fix documentation inconsistencies and missing module docs

[coderabbitai]

Context

Related to PR #424 which refactored the connection module and highlighted documentation quality concerns.

Request from: @leynos
Source: #424

Objective

Address documentation inconsistencies and missing module documentation to improve developer experience and API clarity.

Issues to address

1. WireframeProtocol documentation inconsistency

Problem:
WireframeProtocol documentation shows arbitrary ProtocolError types (e.g., String) at src/hooks.rs:22, but WireframeApp::with_protocol only accepts ProtocolError = () today at src/app/builder.rs:294.

Proposed solutions:

• Option A: Document this limitation explicitly in the builder documentation to set correct expectations
• Option B: Generalise the app/connection pipeline to carry a ProtocolError type parameter to support arbitrary error types as documented

2. Missing module documentation

Problem:
The module src/fragment/tests.rs:1 is missing the required //! module documentation comment.

Solution:
Add appropriate //! module documentation to src/fragment/tests.rs describing the module's purpose and contents.

Benefits

• Improves API documentation accuracy
• Reduces developer confusion
• Ensures consistent documentation standards across the codebase

[traycerai]

Warning

Rate limit exceeded. Please try after 518186 seconds.

[leynos]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Approach

Address documentation inconsistencies in the WireframeProtocol trait (which shows arbitrary ProtocolError types but is constrained to () in practice) and add missing module documentation to src/fragment/tests.rs.

Observations

The Wireframe codebase is a Rust networking framework with a builder-based API pattern. The WireframeProtocol trait in src/hooks.rs defines connection lifecycle hooks with a flexible ProtocolError associated type, but the WireframeApp builder in src/app/builder_protocol.rs constrains this to ProtocolError = (). The src/fragment/ module handles message fragmentation and reassembly, with tests covering FragmentHeader, FragmentSeries, Fragmenter, and Reassembler components.

Assumptions

Assumption 1: Documentation approach for WireframeProtocol inconsistency

Options Considered:

1. Option A - Document limitation: Update documentation to explicitly state that WireframeApp currently only supports ProtocolError = (), while keeping the trait flexible for future extensibility
2. Option B - Generalize pipeline: Add a generic ProtocolError type parameter to WireframeApp and propagate it through the builder pattern

Chosen Option: 1

Rationale: The ticket's primary objective is addressing documentation quality issues from PR #424. The exploration revealed architectural reasons for the () constraint (API simplicity, type erasure, uniform interface), and the connection pipeline is already generic should future generalization be desired. Generalizing now would be scope creep beyond a documentation fix.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Documentation Improvements

This phase addresses both documentation issues: the WireframeProtocol documentation inconsistency and the missing module documentation for fragment tests.

Task 1: Fix WireframeProtocol Documentation Inconsistency

Update documentation in the trait definition and builder to accurately reflect the current ProtocolError = () constraint and set correct developer expectations.

• Update src/hooks.rs trait-level documentation to clarify that while ProtocolError is flexible in the trait definition, WireframeApp::with_protocol currently requires ProtocolError = ()
• Modify the doc examples in src/hooks.rs (around lines 41-55 for handle_error and lines 77-101 for on_eof) to use type ProtocolError = () instead of type ProtocolError = String to reflect actual usage
• Add documentation to the with_protocol method in src/app/builder_protocol.rs explaining the ProtocolError = () constraint and the rationale (API simplicity, type erasure for dynamic dispatch)

Task 2: Add Fragment Tests Module Documentation

Add the required //! module-level documentation comment to the fragment tests module following established codebase patterns.

• Add //! module documentation at the top of src/fragment/tests.rs describing the test suite's purpose (unit testing the fragmentation/reassembly subsystem)
• Document the test coverage areas: FragmentHeader field access, FragmentSeries ordering and validation, Fragmenter splitting and ID management, and Reassembler assembly with size limits and expiry handling
• Follow the documentation style used in other test modules in the codebase (e.g., src/codec/tests.rs)

🤖 Prompt for AI agents

This phase implements documentation improvements to address inconsistencies in
the `WireframeProtocol` trait and add missing module documentation to fragment
tests.

## Fix WireframeProtocol Documentation Inconsistency

In `src/hooks.rs`:
- Update the trait-level documentation for `WireframeProtocol` to clarify that
while `ProtocolError` is a flexible associated type in the trait definition,
`WireframeApp::with_protocol` currently requires implementations to use
`ProtocolError = ()`
- Modify the doc examples around lines 41-55 (for `handle_error`) and lines
77-101 (for `on_eof`) to use `type ProtocolError = ()` instead of `type
ProtocolError = String` to accurately reflect actual usage

In `src/app/builder_protocol.rs`:
- Add documentation to the `with_protocol` method explaining the `ProtocolError
= ()` constraint
- Include the rationale for this constraint: API simplicity, type erasure for
dynamic dispatch, and uniform interface

## Add Fragment Tests Module Documentation

In `src/fragment/tests.rs`:
- Add `//!` module-level documentation at the top of the file
- Describe the test suite's purpose: unit testing the fragmentation/reassembly
subsystem
- Document the test coverage areas:
  - `FragmentHeader` field access
  - `FragmentSeries` ordering and validation
  - `Fragmenter` splitting and ID management
  - `Reassembler` assembly with size limits and expiry handling
- Follow the documentation style and patterns used in other test modules like
`src/codec/tests.rs`

---

🚀 Next Steps

🤖 All AI agent prompts combined

This phase implements documentation improvements to address inconsistencies in
the `WireframeProtocol` trait and add missing module documentation to fragment
tests.

## Fix WireframeProtocol Documentation Inconsistency

In `src/hooks.rs`:
- Update the trait-level documentation for `WireframeProtocol` to clarify that
while `ProtocolError` is a flexible associated type in the trait definition,
`WireframeApp::with_protocol` currently requires implementations to use
`ProtocolError = ()`
- Modify the doc examples around lines 41-55 (for `handle_error`) and lines
77-101 (for `on_eof`) to use `type ProtocolError = ()` instead of `type
ProtocolError = String` to accurately reflect actual usage

In `src/app/builder_protocol.rs`:
- Add documentation to the `with_protocol` method explaining the `ProtocolError
= ()` constraint
- Include the rationale for this constraint: API simplicity, type erasure for
dynamic dispatch, and uniform interface

## Add Fragment Tests Module Documentation

In `src/fragment/tests.rs`:
- Add `//!` module-level documentation at the top of the file
- Describe the test suite's purpose: unit testing the fragmentation/reassembly
subsystem
- Document the test coverage areas:
  - `FragmentHeader` field access
  - `FragmentSeries` ordering and validation
  - `Fragmenter` splitting and ID management
  - `Reassembler` assembly with size limits and expiry handling
- Follow the documentation style and patterns used in other test modules like
`src/codec/tests.rs`

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!