Documentation fixes

[Patrik Stridvall]

> Patrik Stridvall <ps at leissner.se> writes:
> 
> > 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.
> 
> IMO, this is true if we can make the generator work purely on the
> source code, so that you can give it the unmodified source of a
> Windows dll and it spits out the spec file. If you need to add
> comments before each and every exported function, then I don't see
> much advantage to parsing the source. You might as well put all the
> information in the comment (or leave it in the current spec file for
> that matter).

Well, the ordinal of each function and for that that matter 
which functions that should be exported must be specified somewhere.
Currently winapi_extract takes this information from the comment lines
looking like this in the nearest preceding comment:
 *             Foo (BAR.@)
All non-static functions with such preceding comment line(s) is
considered exported using the name specified in the comment
as the external name.

Of course, I can take this information from anywhere, but for 
obvious reason I can't guess it.

If the unmodified source contains Microsoft Visual C++ __declspec(dllexport)
directives or the project has a Microsoft Export file (a .def file) I can
generate a spec file. This is not supported yet, but is no particular
problem supporting in itself.

A little worse problem is that I currently doesn't extract the function
"kinds" (long ptr double str wstr) from the source but use the 
tools/winapi_check/win{16,32}/*.api files to determine the "kinds".
This is not a teoretical problem, however it might take some time to
fix all the same.

But after that winapi_extract will be able to take unmodified source
if __declspec(dllexport) directives or a .def file exists.

However I think we concentrate primarily on the Wine source.
I think as far the it is concerned it will suffice to use comment lines like
 *             Foo (BAR.@)
to extract the normal entries for the spec files.
The stubs and forwards need to have special handling but
then so must it in the case of __declspec(dllexport) directives
or a .def file as well.

There is no problem for winapi_extract to support all the above either
(except implementation time of course).

> Basically, if the source parsing allows doing more than we do now
> (like build spec files for new dlls) it's worthwhile; if all it does
> is generate the existing spec files some other way I don't think
> there's much point. After all, we have the spec files already, and
> they are not going to change much.

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.

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.

> Another use of the source parser could be to generate more detailed
> debugging information for +relay; but in this case I'd say it should
> go to a completely different file, used by some external relay dumping
> program. I don't want all the extra debug information to clutter up
> the spec files.

That is another thing that I have planned to do with
winapi_extract. I don't have any good idea how this should
look like yet. You (or somebody else) are welcome to
write a specification on exactly what you want so I
can fix the how when I have time.