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.
Alexandre Julliard julliard@winehq.com wrote in article 878zh3y8e0.fsf@mail.wine.dyndns.org...
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.
I agree that bloat is a serious danger. To me the issue is that the full documentation is just too big and actually belongs in a decent documentation management environment. To be honest since Wine is a re-engineering of an existing product I actually expect that the full documentation is many times larger than the source, once we start considering the scraps of paper on which we jot down the results of random experiments and the programs written for them. All Microsoft need are the change requests, specs and design docs. We need more.
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.
Yes I am happy with that view. However when I spend four days writing test code and experimenting to find out how 24 different flags interact and proving that the weird code IS wrong. I would like to know where I should put that information.
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.
Bill
-
Alexandre Julliard -
Bill Medland