[Document] MDAnalysis residue handling in WaterBridge

[tani-dubey]

Summary

This addresses the confusion discussed in #299, where users were concerned about duplicated water residues affecting WaterBridge detection. The underlying behavior was confirmed to be correct, but the assumption was undocumented.

By clarifying this in the module docstring, users can better understand:

• why duplicated resid values may appear in raw PDB files
• how MDAnalysis resolves this internally
• and why WaterBridge remains correct without manual deduplication.

Changes

Added description in water_bridge.py

Water-mediated interactions --- :mod:`prolif.interactions.water_bridge`
=======================================================================
.
.
.. versionadded:: 2.1.0

Notes
-----
WaterBridge relies on MDAnalysis residue handling to uniquely identify
individual water molecules.

Due to the 4-digit limitation of residue numbering in the PDB format,
multiple water molecules may appear to share the same residue number
(e.g., ``resid 1917``). MDAnalysis internally guarantees unique residue
identities when parsing PDB files (e.g., by offsetting residue indices).

As a result, WaterBridge correctly treats each water molecule as a
distinct residue, and users do not need to manually deduplicate water
residues when using MDAnalysis-supported formats.

happy to modify pr if required

[github-actions]

Type-checking report

No changes in type-hints coverage 🎉

Overview

.
├── prolif
│   ├── [x] __init__.py
│   ├── [x] _version.py
│   ├── [x] datafiles.py
│   ├── [x] exceptions.py
│   ├── [x] fingerprint.py
│   ├── [x] ifp.py
│   ├── interactions
│   │   ├── [x] __init__.py
│   │   ├── [x] base.py
│   │   ├── [x] constants.py
│   │   ├── [x] interactions.py
│   │   ├── [x] utils.py
│   │   └── [x] water_bridge.py
│   ├── [x] molecule.py
│   ├── [x] parallel.py
│   ├── [x] pickling.py
│   ├── plotting
│   │   ├── [x] __init__.py
│   │   ├── [x] barcode.py
│   │   ├── [x] complex3d.py
│   │   ├── network
│   │   │   ├── [x] __init__.py
│   │   │   └── [x] lignetwork.py
│   │   ├── [x] residues.py
│   │   └── [x] utils.py
│   ├── [x] rdkitmol.py
│   ├── [x] residue.py
│   ├── [x] typeshed.py
│   └── [x] utils.py
├── scripts
│   ├── [x] check_types.py
│   └── [x] test_build.py
└── tests
    ├── [x] __init__.py
    ├── [x] conftest.py
    ├── plotting
    │   ├── [x] __init__.py
    │   ├── [x] test_barcode.py
    │   ├── [x] test_complex3d.py
    │   ├── [x] test_network.py
    │   └── [x] test_residues.py
    ├── [x] test_fingerprint.py
    ├── [x] test_ifp.py
    ├── [x] test_interactions.py
    ├── [x] test_molecule.py
    ├── [x] test_parallel.py
    ├── [x] test_pickling.py
    ├── [x] test_residues.py
    └── [x] test_utils.py

Summary: 43/43 files have complete type hints (100.0%)

Remaining errors

Poe => mypy .
Success: no issues found in 43 source files

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.07%. Comparing base (095ca70) to head (6a99853).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #320   +/-   ##
=======================================
  Coverage   95.07%   95.07%           
=======================================
  Files          23       23           
  Lines        1950     1950           
=======================================
  Hits         1854     1854           
  Misses         96       96           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cbouy]

All looks good, thanks @tanii1125 !