Next: , Previous: Implementation files, Up: Writing modules


4.4 Specification

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

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

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 2010), half of gnulib uses the first practice, nearly half of gnulib uses the second practice, and a small minority uses the texinfo practice.