Re: line-map.c

[Neil Booth <neil at daikokuya dot co dot uk>]

Robert Dewar wrote:-

> > Per has managed to change that file, and he didn't write it, so others
> > do seem quite capable of figuring out what it does.
> 
> That of itself is not really relevant. I am sure there are people who can
> manage to figure out almost anything, but to me the purpose of documentation
> is precisely to *eliminate* the need to "figure out" what a given code unit
> does. 
> 
> In the GNAT world, we always encourage new people reading the sources for the
> first time to point out any place where they feel that more comments could
> have made it easier to read. We almost always consider such comments prima
> facie evidence of inadequate documentation, and we certainly don't think that
> it is enough to point out that some experts very familiar with the system have
> managed to figure things out.

I still don't see what's so unclear about

Map logical line numbers to (source file, line number) pairs.

particularly as we three discussed this in the past!

However, if you give me a rough paragraph you'd like added, I'd be
happy to tweak it and/or apply it.

Neil.