this is not a just a python problem but a problem in many dynamic languages.

switching to the typed variants whether typecript, python type-hints, mypy etc will force you to do the dance to make the compiler happy instead of working on code.

which is why for me - JSDoc is really good - it uses types for documentation and ends there.