Documenting functions

[Alexandre Julliard]

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.

>    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 at winehq.com