1 Aug
2001
1 Aug
'01
5:53 p.m.
Francois Gouget <fgouget(a)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(a)winehq.com
2 Aug
2 Aug
1:13 p.m.
New subject: Documenting functions
Alexandre Julliard <julliard(a)winehq.com> wrote in article
<878zh3y8e0.fsf(a)mail.wine.dyndns.org>rg>...
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.
Bill
Francois Gouget <fgouget(a)free.fr> writes:
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.
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.
8319
days inactive
8320
days old
1 comments
2 participants
participants (2)
-
Alexandre Julliard -
Bill Medland