Define Each behavior when Constants.Null is passed as restriction

[konard]

Summary

Clarifies the Each method behavior when Constants.Null (value 0) is passed as restriction parameters to resolve the confusing behavior described in Issue #173.

Problem

The existing Each method behavior was confusing when Constants.Null (which has value 0) was passed as a restriction parameter. Users expected wildcard behavior but got literal index 0 lookup instead.

Solution

Conservative approach that preserves existing functionality while adding clarity:

1. Enhanced Documentation: Added comprehensive XML documentation to Each method implementations explaining that:

   • Constants.Null (value 0) is treated as literal link index 0
   • Constants.Any should be used for wildcard/unspecified behavior

2. Clarification Extensions: Added ILinksEachClarificationExtensions with helper methods:

   • EachAllLinks() - Clear method for iterating all links
   • EachAnyLink() - Explicit wildcard behavior using Constants.Any
   • EachLinkAtIndexZero() - Explicit method for finding link at index 0
   • EachWithNullValidation() - Validation method that warns about potential Constants.Null misuse

3. Comprehensive Tests: Added EachNullBehaviorTests that document and verify the expected behavior:

   • Tests current behavior with Constants.Null vs Constants.Any
   • Demonstrates proper usage patterns
   • Validates extension methods work correctly

Backward Compatibility

✅ No breaking changes - all existing code continues to work exactly as before.

Key Benefits

• Clarity: Clear documentation removes confusion about Constants.Null vs Constants.Any
• Developer Experience: Extension methods provide clearer API for common use cases
• Validation: Optional validation method helps catch potential misuse
• Testing: Comprehensive tests document expected behavior for future maintainers

Test plan

• All existing tests continue to pass
• New tests verify documented behavior
• Extension methods work as expected
• No performance impact on existing code

Fixes #173

🤖 Generated with Claude Code