"Julio M. Merino Vidal" <jmmv84@gmail.com> writes:
>> I tend to agree that it is necessary to have the comments in the code
>> as well.
>
> Hmm... I initially had all the comments in the source files.  But while
> writing the manual page, I removed them from there to avoid redundancy.
> The comments left in the code are those that do not fit the manual page.
> Sure, we can do both, but that means duplicates :-/

We could generate some of the man page documentation directly from the
source to keep them consistent, perhaps? Lots of projects do that.

> Maybe the manual page currently has too many details (like describing
> each field of each structure), but if this information is not there, it is
> difficult to explain general concepts.

I tend to agree.

Perry