"Bill Medland" <medbi01(a)accpac.com> writes:
> Ay, there's the rub. It isn't our function. It';s Microsoft's function.
> Now was it Holub or McConnell that complains about functions having weird
> behaviour on certain inputs.
IMO Microsoft functions need less documentation than internal ones,
since there is MSDN and other countless books about Windows. You can
assume that people reading your code already know what the various
APIs are supposed to do.
> The biggest problem, I believe, is the functions that take flags. Bear in
> mind that a single DWORD argument used for flags is equivalent to up to 32
> boolean arguments. Documenting the relationship between those is a pain
> but it needs to be done if we expect compatibility.
This is clearly something that is best documented with code, not with
text. You may need pages of text to describe the flags behavior in
English, while with code it's usually only a few lines, plus a few
comments here and there.
This doesn't mean it wouldn't be a good thing to also have the full
description in English; but in a separate document, not in the code.
--
Alexandre Julliard
julliard(a)winehq.com
>>>>> "Medland," == Medland, Bill <Bill.Medland(a)accpac.com> writes:
Medland,> I am not very comfortable with this one but strange as it may
Medland,> seem it solves the problem. I'd love to know why.
Medland,> <<diff13.txt>> Bill Medland (medbi01(a)accpac.com) Prevents
Medland,> excessive clipping in SysListView32.
Medland,>
Medland,>-static inline int perfect_graphics(void)
Medland,>+static int perfect_graphics(void)
Medland,> {
Medland,> static int perfect = -1;
Medland,> if (perfect == -1)
Medland,>
Some C-Expert is requested here, but I suspect that in the old function the
variable "perfect" was created in every instantiation of the
"perfect_graphics" inlined function. Could you perhaps try to declare the
"perfect" outside the inlined function, like
static int perfect = -1;
static inline int perfect_graphics(void)
Bye
--
Uwe Bonnes bon(a)elektron.ikp.physik.tu-darmstadt.de
Institut fuer Kernphysik Schlossgartenstrasse 9 64289 Darmstadt
--------- Tel. 06151 162516 -------- Fax. 06151 164321 ----------
Jeremy White <jwhite(a)codeweavers.com> writes:
> I would say that I would rather have 100% of the effort a
> particular developer *wants* to put in, rather than only
> have his/her coding efforts.
Absolutely; I'm not going to discourage anybody from writing doc if
they feel like it. But I don't want anyone to feel somehow obliged to
spend time on the doc if they'd rather be writing code, which I expect
is the case with most developers...
> However, I think that there should be a standard function
> header, with a standard place to put notes and comments
> in general about a function.
I don't see a need to standardize anything. If you want to add a
comment before a function just do it, there is no need for a standard
format, plain text works just as well.
> I have been trained, and I suspect that many of us have
> been trained, to look at a function header for general
> tips and tricks before diving into the code. I know
> this is sacriledge to you, Alexandre, but there are some
> of us who like to quickly look at a function, rather than
> always reading the code to understand it completely.
I think you misunderstand my position; I'm not opposed to having a
comment at the start of the function explaining the general goal and
the non-obvious things going on. But if you need more than a couple of
paragraphs to do this, then either there are too many non-obvious
things going on in your function, or you are wasting space explaining
the obvious.
I do strongly think that the goal should be to write code that doesn't
require documentation in order to be understood. Of course adding a
small amount of comments is a good idea; but when you start having
more lines of documentation than lines of code, something is very
wrong IMO.
But this is mainly a matter of personal taste, and except in extreme
cases I'm not going to reject code because it has too much (or not
enough) documentation. It may happen that some of your beloved
horizontal lines get lost during the cvs commit though ;-)
--
Alexandre Julliard
julliard(a)winehq.com
[Resend due to exim crash; thanks Ove]
>> 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.
I think this is a dangerous attitude to take. I think that
you cannot (and should not) attempt to force volunteer developers to add
documentation to code. However, there are some few of us,
who don't feel that the job is satisfactorily done until
the documentation reflects important things that we've learned.
I would say that I would rather have 100% of the effort a
particular developer *wants* to put in, rather than only
have his/her coding efforts.
If I, like Bill, spend 24 hours ripping my hair out to
learn some oddball things, I want a place to put those things.
I want someone else (or an older version of me) to have a
chance to not have to learn those things the hard way.
Please don't misunderstand me. I agree that we shouldn't
try to replicate MSDN. I'm not even sure we should provide
minimal documentation like parameter lists and return values.
Further, I agree that where it makes sense, the best place
for comments is inline with the relevant code.
However, I think that there should be a standard function
header, with a standard place to put notes and comments
in general about a function.
I have been trained, and I suspect that many of us have
been trained, to look at a function header for general
tips and tricks before diving into the code. I know
this is sacriledge to you, Alexandre, but there are some
of us who like to quickly look at a function, rather than
always reading the code to understand it completely.
<in joke>
Finally, I think all the code would be dramatically
improved, in fact, I bet we'd be at Wine 1.0 by now,
if there were nice big horizontal separator lines everywhere.
</in joke>
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
Hi all.
I'm working on a no-windows installation. The system is a RH 6.2 system,
upgraded to the latest patches. I've installed XFree4 and KDE 2.1
I'm experiencing an unhandled exception when I try to a VC
application. The application works (almost) fine until it opens a
selection dialog, with a list on it.
As you can see from the trace, it is trying to do an RDW_UpdateRgns with a
wndPtr of 0xffff
Unhandled exception: page fault on read access to 0x08fd506b
in 32-bit code (0x406d1771).
In 32-bit mode.
Symbol h_errno is invalid
Symbol hack_digit is invalid
0x406d1771 (RDW_UpdateRgns+0x3c9 [painting.c:720] in libuser32.so): testb
$
0x10,0x6b(%esi)
720 if( wnd->dwStyle & WS_VISIBLE )
Wine-dbg>bt
Backtrace:
=>0 0x406d1771 (RDW_UpdateRgns+0x3c9(wndPtr=0xffff, hRgn=0x0, flags=0x180,
firstRecursLevel=0x0) [painting.c:720] in libuser32.so) (ebp=405b1bc4)
1 0x406d1787 (RDW_UpdateRgns+0x3df(wndPtr=0x40377824, hRgn=0x0,
flags=0x180, firstRecursLevel=0x0) [painting.c:721] in
libuser32.so) (ebp=405b1c20)
2 0x406d1787 (RDW_UpdateRgns+0x3df(wndPtr=0x40377538, hRgn=0x0,
flags=0x180, firstRecursLevel=0x1) [painting.c:721] in
libuser32.so) (ebp=405b1c7c)
3 0x406d1e08 (RedrawWindow+0x38c(hwnd=0x43f0, rectUpdate=0x0,
hrgnUpdate=0x0, flags=0x180) [painting.c:982] in
libuser32.so) (ebp=405b1cd4)
4 0x406d1f1d (UpdateWindow+0x21(hwnd=0x43f0) [painting.c:1015] in
libuser32.so) (ebp=405b1cf0)
5 0x0043df7a (<Debugged process>.EntryPoint+0x13625 in <Debugged
process>) (ebp=0046e660)
6 0x00000623 (ebp=000044e4)
Just for "fun", I've tryied to add checks for 0xffff, but it crashes when
it enters non Wine DLL (actually they are Spread dlls from Farpoint)
Any clue?
Thanks you all in advance
Bye
Marco
--
Marco Bizzarri - Responsabile Tecnico - Icube S.r.l.
Sede: Via Ridolfi 15 - 56124 Pisa (PI), Italia
E-mail: m.bizzarri(a)icube.it WWW: www.icube.it
Tel: (+39) 050 97 02 07 Fax: (+39) 050 31 36 588
Hi All.
While trying to make an application working under wine, I've stumped
into the following trace fragment, obtained with --debugmsg +relay:
081612c8:Call kernel32.CreateFileA(405f6454
"c:\\rs\\project\\apitest\\vc\\32\\apitestvc60\\debug\\ret_dll.pdb",80000000,00000001,00000000,00000003,00000080,00000000)
ret=404aa001
081612c8:Ret kernel32.CreateFileA() retval=ffffffff ret=404aa001
081612c8:Call kernel32.CloseHandle(ffffffff) ret=404aa0bd
081612c8:Ret kernel32.CloseHandle() retval=00000000 ret=404aa0bd
As you can see, the program is trying to open a file, which is not
found. An invalid handle (ffffffff) is returned. The program however
closes the handle.
My question is: is this correct? Should the CloseHandle check to see if
it is a correct handle?
Thank you all in advance
Marco Bizzarri
--
Marco Bizzarri - Responsabile Tecnico - Icube S.r.l.
Sede: Via Ridolfi 15 - 56124 Pisa (PI), Italia
E-mail: m.bizzarri(a)icube.it WWW: www.icube.it
Tel: (+39) 050 97 02 07 Fax: (+39) 050 31 36 588
Getting back to what we are and are not allowed to do..
Suppose I am looking at a low-level function that I believe is only
75%-complete (the most important 75% of course and no disrespect meant to
those who have got it that far).
One of the problems with it is it is not totally clear EXACTLY what the
function should do in some of its more esoteric modes.
To me the first task is to define what it should do and that should be part
of the documentation of the function.
The particular function currently does not have any true documentation
within the code; the best documentation of what it does is the code itself,
and the best documentation of what it should do is the MSDN description of
the function.
1. Should the function be completely defined in its header in the source
code (which will probably make the header twice as large as the function)
or should the details be put somewhere else.
2. Are we walking into copyright danger if the Wine documentation of the
function is clearly based on the MSDN documentation, even if we acknowledge
that.
3. Are we interested in that level of documentation?
Bill
