On Thu, 11 Sep 2014 19:57:43 +0200 Ulrich Lauther <ulrich.laut...@t-online.de> wrote:
> As I understand it, the man-pages are directed at the user of a > program who wants to know WHAT a program is supposed to do and how > she can control it via options. On Thu, 11 Sep 2014 14:48:51 -0600 Clarke Echols <cla...@verinet.net> wrote: > Ulrich is correct. I was responsible for the HP-UX manpages at HP for > most of five years. > > Manpages (I always used a combined single word) are for users, > programmers, and system admistrators. I think there's some small understanding. I was referring to > >>> - for each class a block of comments explaining what the > >>> class is all about I understood that to refer to the reason the class exists and what it does. That's insignificantly different from section 3 of the manual; the user is the programmer, and the purpose is to explain the *what*, not the how. If by "all about" Urich meant a sentence or two, sure, a comment block is fine. If by "all about" he meant a description of the semantics of the public interface (which is what I thought he meant) then ISTM that belongs in a manual, not in the source code. N'est-ce pas? --jkl
