Documentation fixes

[Alexandre Julliard]

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).

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.

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.

-- 
Alexandre Julliard
julliard at winehq.com