[cfe-dev] [RFC] Removing libclang APIs to traverse the comment AST

[Dmitri Gribenko]

Hello,

I'd like to remove libclang APIs to traverse the comment AST.
Instead, I would recommend to use clang_FullComment_getAsXML, which
provides the same information, but does not expose implementation
details of the comment AST.

Here is the list of libclang APIs I would like to remove:

enum CXCommentKind
enum CXCommentInlineCommandRenderKind
enum CXCommentParamPassDirection

clang_Comment_getKind
clang_Comment_getNumChildren
clang_Comment_getChild
clang_Comment_isWhitespace
clang_InlineContentComment_hasTrailingNewline
clang_TextComment_getText
clang_InlineCommandComment_getCommandName
clang_InlineCommandComment_getRenderKind
clang_InlineCommandComment_getNumArgs
clang_InlineCommandComment_getArgText
clang_HTMLTagComment_getTagName
clang_HTMLStartTagComment_isSelfClosing
clang_HTMLStartTag_getNumAttrs
clang_HTMLStartTag_getAttrName
clang_HTMLStartTag_getAttrValue
clang_BlockCommandComment_getCommandName
clang_BlockCommandComment_getNumArgs
clang_BlockCommandComment_getArgText
clang_BlockCommandComment_getParagraph
clang_BlockCommandComment_getCommentWithIndex
clang_ParamCommandComment_getParamName
clang_ParamCommandComment_isParamIndexValid
clang_ParamCommandComment_getParamIndex
clang_ParamCommandComment_isDirectionExplicit
clang_ParamCommandComment_getDirection
clang_TParamCommandComment_getParamName
clang_TParamCommandComment_isParamPositionValid
clang_TParamCommandComment_getDepth
clang_TParamCommandComment_getIndex
clang_VerbatimBlockLineComment_getText
clang_VerbatimLineComment_getText

The reason to remove all these APIs is simple: providing these APIs
does not allow us to change the underlying AST easily.

Here's the plan:
Clang 3.4 -- the APIs are deprecated.
Clang 3.5 -- the APIs are removed.

Please let me know what you think.

Dmitri

-- 
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at gmail.com>*/