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

[Sean Silva]

Do we have no users? :(

This is a huge API surface area that is being ripped out. The cries of even
a single user that depends on this will forever shatter all confidence in
LLVM's C API stability promise. (also, btw, I wouldn't expect a user of a
stable API to be subscribed to the developer's mailing list of the
project...; that is a key difference between a stable API and a "no
backwards compatibility; the onus is on you to be aware of what is
happening in the codebase" API).

If these API's are deprecated (later to be removed) please write a
migration guide to help existing users transition to the new recommended
approach (also, it would be nice to have some documentation about what the
recommended approach even is!). Can you estimate the expected development
cost required to transition from the old API to the recommended API? (for
example, what if bunding an XML library is not feasible for a user that
depends on this functionality?)

more comments below,

On Tue, Nov 12, 2013 at 8:50 PM, Dmitri Gribenko <gribozavr at gmail.com>wrote:

> 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.
>

What is the alternative? Even with XML output, if a node has some
user-facing property (equivalent to what is exposed by one of these
functions), then you still can't change that property since that will break
users, so I don't really see how this buys any flexibility in changing the
underlying AST.

-- Sean Silva


>
> 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>*/
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20131112/3abe2985/attachment.html>