August 2001 - Wine-Devel - list.winehq.org

Re: Documenting functions
by Alexandre Julliard Aug. 2, 2001

Aug. 2, 2001

"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

1 0

Re: Prevent excessive clipping in SysListView32
by Uwe Bonnes Aug. 2, 2001

Aug. 2, 2001

>>>>> "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 ----------

6 9

Re: Documenting functions
by Alexandre Julliard Aug. 2, 2001

Aug. 2, 2001

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

2 1

Re: Documenting functions
by Jeremy White Aug. 2, 2001

Aug. 2, 2001

[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>

1 0

Re: Documenting functions
by Alexandre Julliard Aug. 2, 2001

Aug. 2, 2001

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 1

Dont allow SetSelectorBase to change into an kernel region
by Uwe Bonnes Aug. 1, 2001

Aug. 1, 2001

Hallo, galep3 crashes with following sequence: 096c7b38:Call KERNEL.189: SETSELECTORLIMIT(0x0d87,0x0000045f) ret=02e7:6fb5 ds=099f 096c7b38:Ret KERNEL.189: SETSELECTORLIMIT() retval=0x0d87 ret=02e7:6fb5 ds=099f 096c7b38:Call KERNEL.187: SETSELECTORBASE(0x0d87,0xc02924e0) ret=02e7:6fc1 ds=099f 096c7b38:Ret KERNEL.187: SETSELECTORBASE() retval=0x0d87 ret=02e7:6fc1 ds=099f ... Unhandled exception: page fault on read access to 0xc0292545 Obviously the application trys to reach some kernel memory. If I only allow to set the selector base when (selector base + selector limit) is smaller than 0x8000000, the application goes on and lets me read an eprom plugged into the Galep3 Programmer. Is the appended fix a right acceptable? Index: wine/memory/selector.c =================================================================== RCS file: /home/wine/wine/memory/selector.c,v retrieving revision 1.39 diff -u -r1.39 selector.c --- wine/memory/selector.c 19 Jul 2001 00:39:10 -0000 1.39 +++ wine/memory/selector.c 1 Aug 2001 17:30:48 -0000 @@ -327,7 +327,12 @@ LDT_ENTRY entry; wine_ldt_get_entry( sel, &entry ); wine_ldt_set_base( &entry, DOSMEM_MapDosToLinear(base) ); - wine_ldt_set_entry( sel, &entry ); + if ((base + wine_ldt_copy.limit[sel >> __AHSHIFT]) > 0x8000000) + { + FIXME("Illegal region base %lx limit %lx\n", base,wine_ldt_copy.limit[sel >> __AHSHIFT]); + } + else + wine_ldt_set_entry( sel, &entry ); return sel; } Bye -- Uwe Bonnes bon(a)elektron.ikp.physik.tu-darmstadt.de Institut fuer Kernphysik Schlossgartenstrasse 9 64289 Darmstadt --------- Tel. 06151 162516 -------- Fax. 06151 164321 ----------

1 1

Strange window handle in the trace
by Marco Bizzarri <m.bizzarri＠icube.it> Aug. 1, 2001

Aug. 1, 2001

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

1 0

CloseHandle with 0xffffffff parameter
by Marco Bizzarri Aug. 1, 2001

Aug. 1, 2001

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

1 0

Documenting functions
by Bill Medland Aug. 1, 2001

Aug. 1, 2001

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

4 3