But that is a good point you make :) Is it maybe not the documentation that matters so much but the semantics communicated through the code itself?

Documentation is important, its just how its done today that bothers me. I have been reading the book "Computational Semantics with Functional Programming" and it has been quite intriguing. I would highly recommend it.