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

[Stefan Seefeld]

On 2011-02-16 03:20, Csaba Raduly wrote:
> 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:

I agree. This is precisely why I'd like to push the handling up in the 
stack, to be able to provide hooks for customization.
The way Synopsis solves this is to store all comments that are in the 
vicinity of declarations, and then let users pick a strategy for 
converting them into documentation. This involves

a) a filter that removes non-document comments (some use "///..." 
comments for docs, some use "/** ...*/", etc.
b) a markup (such as javadoc, or doxygen, or ReStructuredText)

These transformations are performed on the Synopsis ASG, in Python.

Thanks,
         Stefan

-- 

       ...ich hab' noch einen Koffer in Berlin...