Documenting functions

[Bill Medland]

Alexandre Julliard <julliard at winehq.com> wrote in article
<878zh3y8e0.fsf at mail.wine.dyndns.org>...
> Francois Gouget <fgouget at 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