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

[Douglas Gregor]

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