[type0]

It gets outdated fast, it becomes messy and it's difficult to explain all concepts with words etc

[bluestreak]

I totally agree with this. Good codebase evolves all the time thru constant refactoring. Looking after code documentation in this context is a pain.

Complex algos should be covered by tests and not so much by comprehensive documentation.

Code documentation works well on external API, which is meant to be relatively static.