[cfe-dev] [PATCH] libclang interface for comments AST

[Jean-Daniel Dupas]

While you're working on comment parser, you may be interested by this bug:

http://llvm.org/bugs/show_bug.cgi?id=13411

This is a comment that make the comment parser crash (by assertion)

Le 20 juil. 2012 à 18:04, Douglas Gregor <dgregor at apple.com> a écrit :

> 
> On Jul 19, 2012, at 2:18 PM, Dmitri Gribenko <gribozavr at gmail.com> wrote:
> 
>> Hello,
>> 
>> The attached patch adds libclang APIs to walk comments ASTs and an API
>> to convert a comment to an HTML fragment.
> 
> This is awesome. Some minor comments below, but I think this is ready to go in.
> 
>> I implemented error handling as returning bogus-but-safe values.  I am
>> still concerned about this, because if the programmer misuses the API,
>> libclang will work around that silently.  It could be a good idea to
>> add some opt-in debug output for libclang to scream in such cases.
> 
> I think adding opt-in debug output for libclang is a wonderful (separable) idea.
> 
>> For testing I implemented an equivalent of Comment::dump() with these
>> new APIs in c-index-test.
> 
> 
> Great!
> 
> +void CommentASTToHTMLConverter::visitInlineCommandComment(
> +                                  const InlineCommandComment *C) {
> +  StringRef CommandName = C->getCommandName();
> +  bool HasArg0 = C->getNumArgs() > 0 && !C->getArgText(0).empty();
> +  StringRef Arg0;
> +  if (HasArg0)
> +    Arg0 = C->getArgText(0);
> +
> +  if (CommandName == "b") {
> +    if (!HasArg0)
> +      return;
> +    Result += "<b>";
> +    Result += Arg0;
> +    Result += "</b>";
> +    return;
> +  }
> +  if (CommandName == "c" || CommandName == "p") {
> +    if (!HasArg0)
> +      return;
> +    Result += "<tt>";
> +    Result += Arg0;
> +    Result += "</tt>";
> +    return;
> +  }
> +  if (CommandName == "a" || CommandName == "e" || CommandName == "em") {
> +    if (!HasArg0)
> +      return;
> +    Result += "<em>";
> +    Result += Arg0;
> +    Result += "</em>";
> +    return;
> +  }
> 
> Here, we're classifying a subset of the Doxygen inline commands. Can you extract this operation out into a member function of InlineCommandComment, something like
> 
> 	enum CXInlineCommandCommentKind {
> 		ICC_Unknown,
> 		ICC_Bold,
> 		ICC_Code,
> 		ICC_Emphasized
> 	};
> 
> 	CXInlineCommandCommentKind getCommandCommentKind() const;
> 
> or maybe tie it to the rendering of the text, e.g.,
> 
> 	enum CXInlineCommandRenderKind {
> 		ICR_Normal,
> 		ICR_Bold,
> 		ICR_Code,
> 		ICR_Emphasized
> 	}
> 
> 	CXInlineCommandRenderKind getRenderKind() const;
> 
> so that all clients don't need to reinterpret the various Doxygen/HeaderDoc/etc. commands themselves (Unless they want to)? This information would be useful in the libclang API as well, since we expect many clients to use that.
> 
> +/**
> + * \brief Convert a given full parsed comment to an HTML fragment.
> + *
> + * Specific details of HTML layout are subject to change.  Don't try to parse
> + * this HTML back into an AST, use other APIs instead.
> + *
> + * \param Comment a \c CXComment_FullComment AST node.
> + *
> + * \returns string containing an HTML fragment.
> + */
> +CINDEX_LINKAGE CXString clang_FullComment_getAsHTML(CXComment Comment);
> 
> Somewhere, we'll need to document the various classes that the emitted HTML uses (para-brief, para-returns, etc.). I suspect that there might be specific interest in those classes, since that's a (currently hidden, but very important) part of this interface.
> 
> 	- Doug
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev

-- Jean-Daniel