Docs: regularize inline docs and docstrings

[dbqpdb]

Docstrings across the codebase are useful but inconsistent: some mix "what this does" with open design questions and TODOs, some use :param: style, some are prose. Many inline comments restate what well-named code already says.

Proposed pass:

• Pick a docstring style (e.g. Google or NumPy) and apply uniformly.
• Move open design questions and TODOs out of docstrings into GitHub issues so docs reflect intent, not history.
• Drop comments that restate obvious code.
• Keep comments that explain why a non-obvious choice was made (e.g. the rank/file flip notes around numpy indexing — though those would ideally be removed entirely by Refactor: pick one coordinate convention — (file, rank) vs (rank, file) #37).

Related to #1.