On 2 March 2011 00:32, Max TenEyck Woodbury max@mtew.isa-geek.net wrote:
First, it is _not_ a new approach. It has literally decades of application. I first encountered it in the '80s and it was well entrenched even then. Such people as D. Knuth have much to say on the subject.
I don't think anyone is arguing that it is a new concept, or even that it is a bad idea.
It is not even new to Wine. There is a lot of embedded documentation already. It just is not being maintained.
I think what's important to note is that there's a big difference between documenting Wine and documenting the API that Wine implements. If it makes sense for a 1 or 2 line documenting comment to go in to the code that explains the purpose of a function or a variable, then I'm sure AJ would not have an issue with that; but if you're looking at sticking the MSDN articles for win32/win64 into the Wine source, then that's: * bloating the code; * difficult to maintain (i.e., when MS decides to arbitrarily change the way the API works); * not necessary; and * generally a bad idea