refactor: convert informal contract into compile-time checked condition

less bugs in the future
remove obsolete comments

All comments that were duplicate info found on the documentation were
removed because they were outdated already or they were adding
opportunity for out-of-sync conflicting info.

Comments that were just outdated and weren't related to documentation
at all were also removed.