Francois Gouget fgouget@free.fr writes:
So I think the functions implemented in Wine should be fully documented. And the only place to do that is in the code source because this is the only place where they have a remote chance of staying up to date (and also where it's most practical to have it).
I have to disagree here. Yes it would be nice to have a free Win API documentation, but it definitely doesn't belong inside the Wine source. First it would be a huge bloat in the source; and more importantly the Wine source doesn't define the Windows API, it is defined by Microsoft.
Of course developpers are very well-known for hating to document stuff so it's going to be pretty hard to get proper documentation. But we should encourage all Wine developpers to write good documentation for the functions they implement/fix, not dissuade them to do so.
I'd much rather have developers spend their time writing code. Making them duplicate the whole MSDN documentation would be a huge waste of their time. Our resources are not infinite, and it's much more useful to have 100% API coverage with no docs at all than 50% coverage and tons of docs.
Also I agree with you that the strict minimum is to at least document all the undocumented/weird behaviors. Especially since without some sort of documentation the next developper may be tempted to remove what looks like unnecessarily convoluted/obviously wrong code.
That should be done with comments inside the code itself. And in many cases it would actually be better to comment the places where the behavior is not right. What I mean is, instead of adding a comment on every line stating "yes this is what Windows does", I'd prefer adding a comment/FIXME to mark the lines that have been written without checking whether Windows really does it this way.