Re: [Groff] Overview, Sept. 2014

[Ulrich Lauther]

On Thu, Sep 11, 2014 at 05:46:22PM -0400, James K. Lowden wrote:
[ ... ]
> 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?
> 
I was NOT referring in any way to semantics or public interface, but to the 
inner
workings of the implementation and how to make it understandable to a later 
maintainer
(or to the original programmer after a few years).
That should have been clear from the previous discussion on programming style.

To give an example:
The seemingly trivial string searching function strstr() can be implemented 
using
sophisticated algorithms like Rabin–Karp algorithm, Knuth–Morris–Pratt 
algorithm, 
Boyer–Moore string search, ...
Their description belongs NOT into the man-page (though a hint about the 
time-complexity would be nice).
But to understand the source code would be impossible without explanations and 
pointers
to the relevant literature.

        ulrich