"Adam D. Ruppe" <destructiona...@gmail.com> wrote in message news:mailman.226.1256173717.20261.digitalmar...@puremagic.com... > On Wed, Oct 21, 2009 at 08:05:46PM -0500, AJ wrote: >> Well of course header files will have comments. The thing is though, >> tomes >> of documentation are not necessary you have header files. And what are >> the >> chances that the documentation will be in synch with the code if the >> documentation is external? Much better chance of that if the header file >> IS >> the documentation and the code is crafted such that it needs very little >> doc. > > That's what ddoc is all about. > > http://www.digitalmars.com/d/2.0/ddoc.html
Even that is over-kill when formal documentation is not required. "one size fits all" hardly ever does (never?). Sure, if you're Microsoft, you need to formally document in great detail the API. But most development does not require the large-scale solutions. A lot of times (I'd say the common case) does not require external formal documentation. While these kinds of things may be nice in certain situations, they don't wipe out everything else once they are created. My way of thinking is such that eliminates the need for yet another programming task while your's seems to be to take that task for granted and automate it. That's fine, there's no one correct answer other than do it the way you like to. I won't be ditching header files. > > /// Some little documentation > int someFunction(int a, int b) { implementation } > > All in one file.