[cfe-dev] Does SourceLocation need more documentation?

[Sam McCall via cfe-dev]

On Mon, Apr 9, 2018, 20:15 Nico Weber <thakis at chromium.org> wrote:

> On Mon, Apr 9, 2018 at 2:06 PM, Sam McCall via cfe-dev <
> cfe-dev at lists.llvm.org> wrote:
>
>> I never felt that I completely understood the code I wrote/reviewed in
>> tools dealing with SourceLocation. And clangd has had several bugs that
>> boil down to wrong locations in the presence of macros.
>>
>> I couldn't find a good guide for how to think about them, so I spent a
>> while reading the source code and wrote a tool to visualize them, which
>> helped me a lot:
>>   https://imgur.com/f3cXp7E
>>
>
> More documentation is always good, but I for one have no idea what's going
> on in that image, and I like to think that I mostly understand
> SourceLocation :-)
>
That's very useful feedback!
It definitely needs some work, and some text.
But maybe it's just the wrong model.

The idea is that SourceLocation is just a (FileID, offset) pair, and
everyone knows how files and offsets work. So the difficult part is
understanding the real and "virtual" files (SLocEntry) and how they relate
to each other.

The nodes in the diagram are the SLocEntrys in an example program (the
main.cpp file).
The text contents are shown, this is what a (FileID, offset) pair indexes
into. (For expansions, this is the spelling).

The black edges are (immediate) expansion location. This forms the logical
macro expression tree that everyone is familiar with. Partial traversal can
be useful/meaningful.
Labels show what expression in the parent is being substituted.

Yellow edges show (immediate) spelling location. As far as I can tell,
these are mainly useful a) to get the content of expansion SLocEntrys which
don't have buffers and b) to produce diagnostics that reference actual
source code. But partial traversal here doesn't seem to be useful.


>
>>
>> (black edges are expansion, yellow edges are source)
>>
>> Did I miss some documentation of this concept?
>> Would it be worth writing up an article illustrated with some examples,
>> to add to llvm.org? Maybe this is niche or well-understood, interested
>> in what others think.
>>
>> _______________________________________________
>> cfe-dev mailing list
>> cfe-dev at lists.llvm.org
>> http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20180409/ca2419c8/attachment.html>