Normally I would put as many invariants in the types as possible, then tests cover the rest. I'm curious how you do this/what you use it for though. Would be cool if you had any examples.

It isn't documentation. It is example code, in the best case. That shit belongs in other files, not in the main file. There is also a reason why literate programming never took off in general. Good luck getting anything done when 80% (conservatively) of the stuff you have to scroll through contributes nothing to the actual execution of the program and might actually be giving you false impressions of how things need to be done.