Add comprehensive explanation of lending iterators

[Crazytieguy]

This PR adds detailed explanations of what lending iterators are and why they're useful to both the crate documentation and README.

Changes

• Added "What are Lending Iterators?" section to crate docs
• Explained the problem they solve and benefits
• Included GAT trait signature example
• Updated README with concise explanation
• Linked to official GAT announcement blog post

Closes #17

Generated with Claude Code

[claude]

PR Review: Add comprehensive explanation of lending iterators

Thank you for this documentation improvement! The additions significantly improve the crate's accessibility for new users. Here's my feedback:

✅ Strengths

Clear Conceptual Explanation

• The "What are Lending Iterators?" section provides an excellent introduction
• The contrast with standard iterators is well-articulated
• Use cases (overlapping windows, mutable views, streaming parsers) are concrete and helpful

Good Structure

• README now has a clear progression: concept → motivation → example
• Crate docs follow a logical flow: problem → solution → API overview → examples
• The GAT trait signature example is simple and informative

Documentation Quality

• Writing is concise and accessible
• Links to official GAT announcement provide good context
• Examples are practical and demonstrate real use cases

📝 Suggestions for Improvement

Minor Inaccuracy in src/lib.rs:15-18
The statement about slice::windows is slightly misleading:

The standard library's slice::windows returns an iterator, but it must own the slice being iterated over.

Actually, slice::windows does NOT own the slice—it borrows it. The real limitation is that it returns non-overlapping borrows, preventing you from holding multiple windows simultaneously. Consider rephrasing to:

The standard library's slice::windows returns an iterator over windows, but each window 
can only exist while the iterator is borrowed, preventing patterns that need to work 
with the data differently.

Or simply remove this specific example since it might confuse readers about the actual ownership model.

Consistency Note

• In README line 47: "the design choice was" (passive)
• In src/lib.rs line 45: "this crate conditionally implements" (active)

Both are fine, but the active voice in the crate docs reads better and matches the project's technical tone.

Test Coverage
The PR is documentation-only, which is appropriate. However, you might consider adding a doc test to the new crate-level documentation to ensure the examples in the explanation compile. The existing examples at lines 52-114 are good, but a simple example in the "What are Lending Iterators?" section would be even better (though not required).

🔍 Other Observations

No Issues Found With:

• Code quality (N/A - docs only)
• Security concerns (N/A - docs only)
• Performance (N/A - docs only)
• Formatting and style

Closes Issue #17
Appropriate closure of the documentation request.

Final Verdict

This is a high-quality documentation PR that significantly improves the crate's accessibility. The one minor inaccuracy about slice::windows should be addressed, but otherwise this is ready to merge.

Great work on making lending iterators more approachable! 🎉