Improve documentation of modes

[gdalle]

Fix #1881 by adding systematic documentation for the Mode subtypes and helper functions.
This PR doesn't change a single line of actual code.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 71.93%. Comparing base (037dfed) to head (0722824).
Report is 101 commits behind head on main.

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1895      +/-   ##
==========================================
+ Coverage   67.50%   71.93%   +4.42%     
==========================================
  Files          31       31              
  Lines       12668    13652     +984     
==========================================
+ Hits         8552     9820    +1268     
+ Misses       4116     3832     -284     

Flag	Coverage Δ
	71.93% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

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

[gdalle]

@wsmoses this is up-to-date with main and ready for review nb 2

[gdalle]

I've merged the latest changes in main and tried to minimize the diff for the final review