[libclang] Deprecate CXIdxEntityRefInfo in favor of CXSymbolRole, for better reference highlighting

MaskRay · February 9, 2018, 12:25am

Hello,

tl;dr ⚙ D42895 [libclang] Add `CXSymbolRole role` to CXIdxEntityRefInfo

In clang/Index.h at master · llvm-mirror/clang · GitHub,
CXIdxEntityRefKind is used to express Objective-C implicit reference
(I cannot found its use in C/C++).

CXIdxEntityRef_Implicit is assigned when a symbol occurrence has the
`Implicit` bit of enum IndexSymbol

github.com

llvm-mirror/clang/blob/master/include/clang/Index/IndexSymbol.h#L91

      
        
              TemplatePartialSpecialization = 1 << 1,
              TemplateSpecialization        = 1 << 2,
              UnitTest                      = 1 << 3,
              IBAnnotated                   = 1 << 4,
              IBOutletCollection            = 1 << 5,
              GKInspectable                 = 1 << 6,
              Local                         = 1 << 7,
              /// Symbol is part of a protocol interface.
              ProtocolInterface             = 1 << 8,
            };
            static const unsigned SymbolPropertyBitNum = 9;
            
            
/// Set of roles that are attributed to symbol occurrences.
            ///
            /// Low 9 bits of clang-c/include/Index.h CXSymbolRole mirrors this enum.
            enum class SymbolRole : uint32_t {
              Declaration = 1 << 0,
              Definition = 1 << 1,
              Reference = 1 << 2,
              Read = 1 << 3,
              Write = 1 << 4,

It turns out that IndexSymbol has more roles (Read/Write/Call) that
fit well with Language Server Protocol `DocumentHighlightKind`, which
can be used to differentiate Read/Write references of a symbol.

I have a pending revision ⚙ D42895 [libclang] Add `CXSymbolRole role` to CXIdxEntityRefInfo to add
support for CXSymbolRole in libclang. I intended to deprecate
CXIdxEntityRefKind in my first version because the feature is fully
covered by SymbolRole. But my reviewer suggested me asking for API
deprecation opinions on cfe-dev. What do you think?

Someone told me Clion differentiates read/write references. With
SymbolRole exposed to libclang, other libclang users (e.g. some C++
language servers/IDE plugins) can benefit from this.

Also appreciated if someone could tell me who is the owner of libclang
or who can make these decisions about API deprecation.

//////////////////////// this is fully covered by SymbolRole
/**
* \brief Data for IndexerCallbacks#indexEntityReference.