line-map.c

[Richard Kenner]

    I think that the comment in the 1st line, plus the wealth of comments
    in line-map.h, is more than enough.

I don't.  There are indeed a lot of detailed comments, but there is no single
paragraph that gives the motivation, in general terms, of the file.

"Map logical line numbers to (source file, line number) pairs."  doesn't
really say that much.  If it were expanded by a few more sentences, it would
be really helpful.

    The code isn't exactly complicated.

No, but the comments I'm talking about aren't about the *code*, but about the
overview of what it's for and how it works.  That's independendent of the
complexity of the code or how easy it is to modify the code.

The reason this came up is that I want a feature that's in general terms,
similar to this.  But without more of an overview of what this is, and what
it's used for, I can't tell whether I can use it for my purposes or not.

The one thing that you can never get by reading code or detailed comments
from the code is the intent of the author.  That's why those are the
most important comments of all.