Documentation fixes

[Patrik Stridvall]

> Patrik Stridvall <ps at leissner.se> writes:
> 
> > 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.
> 
> That's quite ugly IMO.

The #if 0 #endif or having to have a documentation comment at all?

Anyway the #if 0 is not needed I thought it might be needed
in some cases but it is not. I mistakingly believed it might
be type conflicts but it can't be since any exported function
must of course use the C library types otherwise you can't
export them directly.

If you are refering to the documentation comment, I can't
really see why. All other functions have it and adding
additional documentation might be a good idea in some cases
as well.

Furthermore the extern declaration makes it possible
for the C compiler to check that the prototype is
the same as the prototype in the included files.
I spotted several error when doing the patch because of this.

As hinted above, I have implemented a working solution that does
what I have described above. See separate mail.

> As long as we require comments, we might as
> well put everything explicitly in the comment, something like:
> 
> /* ##spec## msvcrt "@ cdecl strcpy(ptr str) strcpy" */
> 
> (we can probably come up with a better syntax, but you get the idea).
> Then we can simply grep for '##spec##' and extract everything into the
> spec file. We can do the same for forwards etc. (and in fact we could
> do it for normal entry points as well).

For forwards, stubs and other special cases, perhaps.
I don't like it very much but it is acceptable.
But we need not decide that now. I will
think more about it and come back later with
some kind of proposal that might or might not
match yours. I'm not sure, we will see.

For normal entry point, however, I respectfully disagree.
One of the major reasons of having automatically
generated .spec files is to avoid having to
store redundant information. The needed information
is already in the C function declaration and storing
in a comment as well brings us back to the current
situation. Sure it makes that generator less
complicatated but it really isn't that important
as long as it is reliable and not ambigeous.

PS. For the record: I consider winapi_extract a prototype
not something that nessary will finally use in "production".
We might of course use it, but I would rather rewrite it so
it becomes simpler and more reliable. Perhaps it shouldn't
be in Perl but in C instead? Oh, well, that is a minor issue
compared to how the information should be stored.