python + libclang;来回迭代 : binding field comments to the field

Question

我现在苦苦挣扎了一段时间，想找到一种合适的方法来将 C++ 结构中的字段绑定(bind)到它的注释，使用 libclang 3.9.1和 python 3.5.2。

到目前为止，我已经安装并运行了这个设置:假设我有文件 Foo.h:

typedef int arbType;

struct Foo {
    //First bar comment
    //Second bar comment
    int Bar; //Third bar comment - after bar

    /* First line baz comment - before baz
       Second line baz comment - before baz
    */
    arbType Baz; //Third line baz comment - after baz
};

我的 python 代码只提取行内注释:

#bind_comments.py
import clang.cindex

def get_cur_comments(cursor):
    comment = ''
    print ('\nGetting comment for:', cursor.spelling.decode())
    parent_cur = cursor.lexical_parent
    token_iter = parent_cur.get_tokens()
    for token in token_iter:
        if token.cursor == cursor:            
            while token.kind.name != 'PUNCTUATION':
                token = next(token_iter)
            token = next(token_iter)
            if token.kind.name == 'COMMENT':
                comment = token.spelling.decode().strip('/')
    return comment

def main():
    index = clang.cindex.Index.create()
    tu = index.parse(b'Foo.h', [b'-x', b'c++'])
    tu_iter = tu.cursor.get_children()
    next(tu_iter)
    root_cursor = next(tu_iter)

    for cur in root_cursor.type.get_fields():
        print(get_cur_comments(cur))

if __name__ == '__main__':
    main()

输出:

C:\>bind_comments.py

Getting comment for: Bar
'Third bar comment - after bar'

Getting comment for: Baz
'Third line baz comment - after baz'

现在，对于我的问题，按重要性降序排列:

1. 如何绑定(bind)字段之前的注释？我查看了 python 中的许多“偷看”解决方案，以便在我迭代 token 时找出下一个是否是我感兴趣的光标(字段)，但没有发现我可以在我的案例中正确实现.为了向您展示我有多认真，以下是我看过的一些解决方案:

   • 问:how-to-look-ahead-one-element-in-a-python-generator
   • 代码配方:look-ahead-one-item-during-iteration
   • 只是另一个代码配方:peek-ahead-an-iterator

2. 概念缺陷:我还不知道如何区分:

   struct Foo {
      int Bar; // This comment belong to bar
               // As well as this one
   
      // While this comment belong to baz already
      int Baz;
    };
   

3. 性能问题:请注意，对于每个字段，我正在遍历其结构的整个标记列表。如果它很大，而且我有很多代币——我想我会为此付出代价。我想找到一些捷径。我考虑过将标记保存在全局列表中，但是如果该字段是另一个结构/类的声明怎么办？将他们 parent 的 token 添加到列表中？这开始变得困惑......

只是那些还不知道 libclang 的人的 helper :

>>> print(root_cursor.spelling.decode())
Foo
>>> root_cursor.type.get_fields()
<list_iterator object at 0x0177B770>
>>> list(root_cursor.type.get_fields())
[<clang.cindex.Cursor object at 0x0173B940>, <clang.cindex.Cursor object at 0x017443A0>]
>>> for cur in root_cursor.type.get_fields():
...   print (cur.spelling.decode())
...
Bar
Baz
>>> root_cursor.get_tokens()
<generator object TokenGroup.get_tokens at 0x01771180>

Answer 1

libclang 使用 Cursor 属性 brief_comment 和 raw_comment 为提取 javadoc 样式注释提供直接支持

稍微调整一下您的输入代码:

s = '''
typedef int arbType;

struct Foo {
    /// Brief comment about bar
    ///
    /// Extra Text about bar
    int Bar; 

    /** Brief comment about baz
     *
     * Extra Text about baz
     */
    arbType Baz; 

    /// Brief only comment
    int blah;
};
'''

import clang.cindex
from clang.cindex import CursorKind

idx = clang.cindex.Index.create()
tu = idx.parse('tmp.cpp', args=['-std=c++11'],  unsaved_files=[('tmp.cpp', s)],  options=0)
for c in tu.cursor.walk_preorder():
    if c.kind == CursorKind.FIELD_DECL:
        print c.brief_comment
        print c.raw_comment
        print 

产生:

Brief comment about bar
/// Brief comment about bar
    ///
    /// Extra Text about bar

Brief comment about baz
/** Brief comment about baz
     *
     * Extra Text about baz
     */

Brief only comment
/// Brief only comment