On November 1, 2002 07:12 am, Christian Neumair wrote:
Comments on that, please :)
Well, here it goes: -- I don't care much about DESC. In fact, it should be painfully obvious what the file is for in 99.99% of the cases. If you feel like adding it, sure, go ahead, you can add a small blurb, without the DESC tag. It's clear what it does, or the description is b0rken :) -- I don't think FUNC section is a good idea. It server no purpose (almost all we do is documented by MS, just go read that docu), and besides, can be automatically extracted from the source. I think we should add the *absolute* minumum docs, and not more: this way people will actually add the essential things, easier to maintain, less chance of bitrot. This one fails the test. -- The TODO & BUGS sections are very useful (I mean, more than words can say), assuming they define a close universe. That is, they document all that's left to do, so I don't have to go understand all code to figure this out. This is where people with good domain knowledge should do a quick brian dump. It's not much work, and it helps other developers plenty. A good way to keep track of progress, and status, BTW.