Hi,
Many Gnulib modules are only documented in the source code. This is fine
with me, but I have noticed two situations that make it hard to predict
where they will be.
First, some modules have documentation above the function declaration
only in the compiled *.c files. The associated header is empty aside
from the declarations. Typically I open the header first expecting to
see documentation, and I expect most others do the same. An example of
this can be seen in lib/yesno.{c,h}.
Second, some modules have the same documentation in both the compiled
*.c files and associated headers. I dislike this because when changing
these functions, one has to make sure that both instances of the
documentation are updated. If one is forgotten, which I find easy to do,
another developer will be confused by the conflicting documentation and
have to do some extra work looking through the ChangeLog. An example of
this can be seen in lib/gcd.{c,h}.
I would like to write two patches. The first will handle the first case
by moving documentation above functions, macros, etc. from the *.c files
to the corresponding *.h files. The second will remove duplicate
documentation from *.c files where documentation is already in the
corresponding *.h files.
Before sending these large patches, I figured it would be best to ask
for others opinions on this. Is there any disagreement with my
preferences here?
Collin
