Documentation fixes

[Patrik Stridvall]

> > The problem is that if I say that the memory directory doesn't
> > "belong" to dlls/user/user.spec winapi_{check,extract,fixup} will
> > not find implementations for all functions, which will cause
> > problems.
> > 
> > For example how should winapi_extract know that I should 
> generate the line
> > 471 pascal16 lstrcmpi(str str) lstrcmpiA
> > when it generates the spec files?
> 
> Well, it's a more general problem, namely that the spec files can
> reference functions that are not implemented directly in the dll.
> 
> You also have for instance:
> 
> @ cdecl strcpy(ptr str) strcpy
>
> in MSVCRT, and strcpy is clearly not implemented there since it's in
> the C library. So you cannot assume that only the functions contained
> in the dll can be used in the spec files, it is legal for the spec
> file to reference external functions.

True. I didn't even thought of that particular problem. Functions like
strcpy is currently suppressed by having it listed in
tools/winapi_check/nativeapi.dat, but that is a little kludgy.

[Thinking...]

Well you could simply have an function
documentation comment without a function implementation in
some file that belongs to MSVCRT.

Like:

/***********************************************************************
 *                strcpy (MSVCRT.@)
 */
#if 0 /* Suppress warnings */
extern char *strcpy(char *dest, const char *src);
#endif 

Perhaps we could do the same with atom functions and lstrcmpi?
The #if 0 #endif isn't even needed for them I believe.

> > I think that we need to move the solution of this problem one step
> > up the "ladder" and discuss the more general problem:
> > How should we store the information needed to generate
> > the spec files in the source, especially concerning
> > the forwards and stubs?
> 
> You'll need a file somewhere that specifies all the entries that
> cannot be determined automatically from the source. You simply cannot
> build a 100% correct spec file based only on the function comments.

Yes. I have some ideas, but no really good one. My currently
best suggestion is having a .spec.in file that approximately
looks like the .spec files but supports configure like substitutions.

foo.spec.in:
---8<---
name foo
type win32
init @init@
rsrc foo.res

import baz.dll

@debug_channels@

101 forward Bar BAZ.Bar
102 stub BarFoo
@fixed@

@ forward Foo BAZ.Foo
@ stub FooBar
@unfixed@
---8<---

And simply let winapi_extract or whatever simple substitute
@init@, @debug_channels@, @fixed@ and @unfixed@ with what can
be extracted from the source.

> And you definitely do not want to need to parse KERNEL source files
> (like the ones in memory/) to build the USER spec file.

Of course. The question was whether the memory directory belongs
to USER or not. I have now accepted that it does not.