My purpose for using documentation
I have no idea if this comment is useful to anyone else, because I'm a novice who is working in a number of languages--formerly a senior technical writer, which also changes my perspective.
As I prepare for a programming task and start to flesh it out, I use the comments sections that I create on the fly for brainstorming, planning, and stream of consciousness reflections on where I'm going and why.
This means that my to-do list for any section is always right there in the code where I'm working on, as well as all of those crazy ideas that come out of nowhere and seem to get lost in the shuffle if you don't process them somehow.
When I'm done with a piece of code, I can remove all the crap, store ideas that are still relevant in another location, and edit what remains down to a fairly good description of why I'm doing certain things. Maybe if I was a more mature coder, this would all seem like a useless exercise, but for me, where I'm at, it makes the documentation part totally useful to me personally and ultimately creates better comment documentation for others.
When I worked at Fujitsu in the late 90s, I corresponded with Sun programmers about a module that they had for exporting javadocs into FrameMaker, and they responded by reworking the module to do exactly what I needed it to do. I did this because maintaining documentation in printed APIs and in code meant that I could never keep up. The new system allowed me to write once, publish in two places.
So I have a lot of respect for those comment sections.
