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

[Fāng-ruì Sòng via cfe-dev]

Hello,

tl;dr https://reviews.llvm.org/D42895

In https://github.com/llvm-mirror/clang/blob/master/include/clang-c/Index.h#L6093,
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
https://github.com/llvm-mirror/clang/blob/master/include/clang/Index/IndexSymbol.h#L91

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 https://reviews.llvm.org/D42895 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.
 *
 * This may be deprecated in a future version as this duplicates
 * the \c CXSymbolRole_Implicit bit in \c CXSymbolRole.
 */
typedef enum {
  /**
   * \brief The entity is referenced directly in user's code.
   */
  CXIdxEntityRef_Direct = 1,
  /**
   * \brief An implicit reference, e.g. a reference of an Objective-C method
   * via the dot syntax.
   */
  CXIdxEntityRef_Implicit = 2
} CXIdxEntityRefKind;

////////////////////////////// The C++ interface has useful Read/Write/Call

/// 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,
  Call        = 1 << 5,
  Dynamic     = 1 << 6,
  AddressOf   = 1 << 7,
  Implicit    = 1 << 8,

  // Relation roles.
  RelationChildOf     = 1 << 9,
  RelationBaseOf      = 1 << 10,
  RelationOverrideOf  = 1 << 11,
  RelationReceivedBy  = 1 << 12,
  RelationCalledBy    = 1 << 13,
  RelationExtendedBy  = 1 << 14,
  RelationAccessorOf  = 1 << 15,
  RelationContainedBy = 1 << 16,
  RelationIBTypeOf    = 1 << 17,
  RelationSpecializationOf = 1 << 18,
};