---

4.4 Specification

The specification of a function should answer at least the following questions:

• What is the purpose of the function?
• What are the arguments?
• What is the return value?
• What happens in case of failure? (Exit? A specific return value? Errno set?)
• Memory allocation policy: If pointers to memory are returned, are they freshly allocated and supposed to be freed by the caller?

Where to put the specification describing exported functions? Three practices are used in gnulib:

• The specification can be as comments in the header file, just above the function declaration.
• The specification can be as comments in the implementation file, just above the function definition.
• The specification can be in texinfo format, so that it gets included in the gnulib manual.

In any case, the specification should appear in just one place, unless you can ensure that the multiple copies will always remain identical.

The advantage of putting it in the header file is that the user only has to read the include file normally never needs to peek into the implementation file(s).

The advantage of putting it in the implementation file is that when reviewing or changing the implementation, you have both elements side by side.

The advantage of texinfo formatted documentation is that it is easily published in HTML or Info format.

Currently (as of 2020), 70% of gnulib uses the first practice, 25% of gnulib uses the second practice, and a small minority uses the texinfo practice.