Hi, Ulrich 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. > > Comments in the source are directed at the programmer, who wants to > understand HOW the functionality of the program is accomplished.
I don't think it's that simple. man pages include file formats, special files, e.g. devices, and a catch-all miscellaneous, section 7, where much groff stuff hangs out. I've certainly seen program internals documented in man pages; not section 1 or 8, but a specific `internals' man page. perlguts(1) for example, divulges a lot of the higher-level internals to make it easier to read the source. I've written foodev(7) to accompany foo(1) several times over the years, outlining the internal structure of the program and how it fits together. (Bell Labs used to release papers alongside the man pages, but that was more to introduce novel programs, e.g. yacc, than explain their source.) I agree, inline comments are needed on a localised basis, before a non-obvious bit of code say, and in particular I find it handy to comment data since the code that describes its use can be scattered. And that seems to be the case on the first file I picked on: http://git.savannah.gnu.org/cgit/groff.git/tree/src/roff/troff/input.cpp#n109 I think what's missing is a higher-level view of how the source fits together, and that's probably why Werner's enthusiastic about a comment-block per class. Without an overview, reading the source tends to be bottom-up; one pieces together enough fragments to recognise a section of the puzzle. With it, you've a rough idea what piece belongs where even if you haven't found it's exact spot yet. Perhaps those on the list that can grok C could have a go at doing Werner's class comments, just as we re-set O'Reilly's _Unix Text Processing_ book. But would it require copyright assignment? That's been a stumbling block for me in the past. Mind you, Bradley M. Kuhn, an FSF board member, wrote http://ebb.org/bkuhn/blog/2014/06/09/do-not-need-cla.html so perhaps there's movement there. :-) Cheers, Ralph.
