Documentation fixes

[Patrik Stridvall]

> Patrik Stridvall <ps at leissner.se> writes:
> 
> > Well, there is the issue of maintaining redundant information.
> > Sure winapi_check can (and indeed was the original reason for it)
> > find missmatchs. But given the number of errors I have seen people
> > make that winapi_check detected, we really should avoid having
> > redundant information if we can.
> 
> If there is an easy way to avoid it, sure. But if it requires a Perl
> script as complex as winapi_check, especially the maintaining of the
> *.api files, I'm not sure it's a win. 

Well the *.api files (or at least the manual maintainance of them)
will be eliminated some day. I will just have to implement parsing
of the "typedefs" in the headers.

However, note that I'm not suggesting that we change to automatic
generation of spec files right now, but at some point in the future.
What tool we should for it is a later problem. With the exception
of which types maps to which "kinds" (long ptr str wstr) the tool
will not nessarily be very complex and I'm not sure what the parsing
of typedefs to find out will be very complex either. But I wont know
until I try.

What primarily intrests me now is how should the needed information be
stored? The problem with normal entry point is solved, the question is
how the stubs and forwards should be stored? Before we know that
we can't really write any working extraction tool can we?

While I'm not entirely happy with your:
/* ##spec## foo "@ forward bar(ptr str) BAZ.bar" */
solution it is the better that any ideas I have.
Simplicity has its charm. :-)

Then we could just, taking USER as example add

/* ##spec## user "name user" */
/* ##spec## user "type win16" */
/* ##spec## user "heap 65520" */
/* ##spec## user "file user.exe" */
/* ##spec## user "owner user32" */
/* ##spec## user "rsrc resources/version16.res" */

/* ##spec## user "2 stub OldExitWindows" */
/* ##spec## user "3 stub EnableOEMLayer" */
/* ##spec## user "4 stub DisableOEMLayer" */
/* ... */

in a appropriate place in say dlls/user/user_main.c.

The order that winapi_extract finds the directive is not important
the .spec file format happends to make it possible to always get
everything in the right order anyway.

However this solves the header, the debug_channels, forwards
and stubs problem and could be used to solve the remaining
problems with "Exported external functions" but I would rather
have it solved with my patch with that name, that you didn't
apply when applying the other patches.

So will accept such a solution? 

While we probably should not actually change the .c files to 
look like this until we have a tool of acceptable complexity
that can generate the .spec files, there is quite a few preparations
that need to be done before that and I would really like to have the
"Exported external functions" patch applied in the meantime
for other reasons like winapi_check likes to know where all
the DLL:s functions are "implemented".

> And it seems to me you are
> finding a lot more errors in the comments than in the spec files ;-)

Well, considering that our developers have neglected the comments
for many year and only changing the spec files that is not
very suprising. That is the problem with having redundant information,
most developers only change where it really count either out of
ignorance or lack of time.
 
> > In addition it will be much easier for the developers (especially
> > newbies). If you change the prototype in the .c files or the
> > ordinal in the comment above it, it will be enough. Stub files
> > will be something normal developers needn't concern himself with.
> 
> If normal developers need to change the spec file for an existing
> function, something is seriously wrong. The spec entry is dictated by
> the dll interface, and there is no reason to change it (except maybe
> to change a 'ptr' into an 'str', but this is a cosmetic issue).

Well, you also have implementing new functions.
You have FooA and want to implement FooW for example.
It is much easier and much more natural to be able to just
cut and paste without having to change the spec files.
I have seen many such errors detected by winapi_check
over the years.