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

[Csaba Raduly]

On Tue, Feb 15, 2011 at 10:44 PM, Stefan Seefeld wrote:
(snip)
> 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.
>
> (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.

I don't think the "who does this comment belong to" problem is
solvable in the general case:

enum E {
  e0,
  // e0 docs or e1 docs ?
  e1
};

The convention used by Doxygen is that /// comments and /** */
comments refer to the next declaration, whereas ///< and /**< */ refer
to the previous one. Of course, this is is no help in the general
case.

Csaba
-- 
GCS a+ e++ d- C++ ULS$ L+$ !E- W++ P+++$ w++$ tv+ b++ DI D++ 5++
Life is complex, with real and imaginary parts.
"Ok, it boots. Which means it must be bug-free and perfect. " -- Linus Torvalds
"People disagree with me. I just ignore them." -- Linus Torvalds