I agree that it's very easy to "misspeak" in C++ or C. It's even easier to mislead or obfuscate what's going on (i.e. write correct code that others can't easily understand). So this sort of documentation is great and I applaud you for adopting it.

That said, the fact that such extensive documentation is necessary (or at the very least nice) suggests to me that you'd be better off using a cleaner, more powerful <http://www.paulgraham.com/power.html>; language that: (1) documents itself to some degree through more elegant syntax (2) takes care of low-level tasks that clutter and confuse otherwise clean code (resource allocation, memory management, etc.) and (3) requires less code to do the same thing, which means fewer lines to document.

There are a bunch of great languages out there that are far more powerful (in terms of abstraction) than C++ or C. Haskell, Lisp, ML, F#, to name just a few. You might consider checking some of these out if you haven't already.