Re: [Bug-gnulib] putting identical comments in both .c and .h files: what do you think?

[Bruno Haible]

Paul Eggert writes:

> > This is also based on the respective frequency of these development
> > actions:
> >   1) [Frequent] Read the specification of a function.
> >   2) [Less frequent] Read or update the implementation of the
> >      function.
> >   3) [Rare] Change the specification of a function.
> 
> But there's something even more common than those, namely:
> 
>     0) [Most frequent] Remind yourself about the specification.
> 
> By far the most common thing that I do is to remind myself about what
> order the arguments are, or something like that.

This is easy: Glance at the .h file, locate the start and end of
/* comments */, and read only the first sentence of the function's
specification.

> So I tend to prefer a .h file that is short and sweet.  I'd rather
> not wade through a .h file that looks like a Unix man page; I'd
> rather glance at one that looks like a Unix man page's synopsis.

But then comes the point where you want to know more. Where do you
look then? Let's take an example: iconv.h

  /* Allocates descriptor for code conversion from encoding `fromcode' to
     encoding `tocode'. */
  extern iconv_t iconv_open (const char* tocode, const char* fromcode);

In gnulib we don't have manpages (yet). You ask yourself: what if the
descriptor cannot be allocated? In gnulib you would look into the .c
file. But this highly increases the risk that you then rely on
undocumented and unwarranted internals of the function.

What's the solution? I think, either we start a texinfo or manpage
documentation of gnulib - in this case I can agree that a single
sentence is enough in the .h file [like it is for glibc] - or we keep
being lazy :-), and then all the doc belongs in the .h file.

Bruno