[cfe-dev] RFC: visiting cursors "backwards" ?

[Douglas Gregor]

On Feb 15, 2011, at 1:44 PM, Stefan Seefeld wrote:

> On 2011-02-15 16:17, Douglas Gregor wrote:
>>> Thus: Is there a way to locate the previous sibling cursor for any given
>>> cursor ? (This may be a null cursor, if the given cursor is the first
>>> child of its parent. That's fine, as in that case I would start from the
>>> parent's start location itself.)
>> There's no way to do this, aside from walking through all of the parent's children again and keeping track of the previous child. We've generally avoided this since it will add another pointer to the size of every declaration node, and we try to keep the AST small.
> 
> OK. Hmm, I could indeed record "previous" cursors as I'm traversing the AST, allowing me to access the comments at the same time as translating the clang AST into the Synopsis ASG. That would avoid the need for libclang to have to know anything about comment <-> declaration associations.

Yes, that'd work.

> (The reason I'd very much prefer to keep this away from libclang is because these associations tend to be a matter of customization, and hard to support on a low level. Consider this:
> 
> // E docs
> enum E {
>  e0,    //< e0 docs
>  e1}; //< e1 docs
> 
> 
> I think the meaning (and logical attachment) of the comments is rather obvious. Yet, this is tricky to implement: Sometimes the comments precede the declaration they are associated with, sometimes they follow them. Sometimes they are even outside the parent cursor's range.
> 
> To support that inside libclang, one would have to parse the comment, using specific rules and markup. I'd rather leave such markup choices to the user who embeds documentation into his code.


Because it's tricky to implement, it's a good candidate for going straight into Clang so that nobody has to do this work again. But, it's up to you.

	- Doug