[cfe-commits] r160595 - in /cfe/trunk: include/clang-c/Index.h test/Index/annotate-comments.cpp tools/libclang/CXComment.cpp
Jordan Rose
jordan_rose at apple.com
Mon Jul 23 08:21:16 PDT 2012
For styles which apply to ALL parameters, it might be nice to have a class on the DL as well...though I guess "div.doxygen dd" would work as well.
On Jul 20, 2012, at 6:47 PM, Dmitri Gribenko wrote:
> Author: gribozavr
> Date: Fri Jul 20 20:47:43 2012
> New Revision: 160595
>
> URL: http://llvm.org/viewvc/llvm-project?rev=160595&view=rev
> Log:
> Comment to HTML conversion: add more CSS classes to identify function arguments
> by index. This is useful if the user does not document all arguments, and we
> can't find a particular argument by index via :nth-of-type() CSS selector.
>
> Modified:
> cfe/trunk/include/clang-c/Index.h
> cfe/trunk/test/Index/annotate-comments.cpp
> cfe/trunk/tools/libclang/CXComment.cpp
>
> Modified: cfe/trunk/include/clang-c/Index.h
> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang-c/Index.h?rev=160595&r1=160594&r2=160595&view=diff
> ==============================================================================
> --- cfe/trunk/include/clang-c/Index.h (original)
> +++ cfe/trunk/include/clang-c/Index.h Fri Jul 20 20:47:43 2012
> @@ -3563,8 +3563,12 @@
> * \li "para-returns" for \\returns paragraph and equivalent commands;
> * \li "word-returns" for the "Returns" word in \\returns paragraph.
> *
> - * Argument list is rendered as \<dl\> list with arguments sorted in function
> - * prototype order.
> + * Function argument documentation is rendered as a \<dl\> list with arguments
> + * sorted in function prototype order. CSS classes used:
> + * \li "param-name-index-NUMBER" for parameter name (\<dt\>);
> + * \li "param-descr-index-NUMBER" for parameter description (\<dd\>);
> + * \li "param-name-index-invalid" and "param-descr-index-invalid" are used if
> + * parameter index is invalid.
> *
> * \param Comment a \c CXComment_FullComment AST node.
> *
>
> Modified: cfe/trunk/test/Index/annotate-comments.cpp
> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/test/Index/annotate-comments.cpp?rev=160595&r1=160594&r2=160595&view=diff
> ==============================================================================
> --- cfe/trunk/test/Index/annotate-comments.cpp (original)
> +++ cfe/trunk/test/Index/annotate-comments.cpp Fri Jul 20 20:47:43 2012
> @@ -483,7 +483,7 @@
> // CHECK-NEXT: (CXComment_BlockCommand CommandName=[returns]
> // CHECK-NEXT: (CXComment_Paragraph
> // CHECK-NEXT: (CXComment_Text Text=[ Ccc.]))))]
> -// CHECK: annotate-comments.cpp:271:6: FunctionDecl=comment_to_html_conversion_11:{{.*}} FullCommentAsHTML=[<dl><dt>x1</dt><dd> Aaa.</dd></dl>]
> +// CHECK: annotate-comments.cpp:271:6: FunctionDecl=comment_to_html_conversion_11:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-0">x1</dt><dd class="param-descr-index-0"> Aaa.</dd></dl>]
> // CHECK-NEXT: CommentAST=[
> // CHECK-NEXT: (CXComment_FullComment
> // CHECK-NEXT: (CXComment_Paragraph IsWhitespace
> @@ -491,7 +491,7 @@
> // CHECK-NEXT: (CXComment_ParamCommand in implicitly ParamName=[x1] ParamIndex=0
> // CHECK-NEXT: (CXComment_Paragraph
> // CHECK-NEXT: (CXComment_Text Text=[ Aaa.]))))]
> -// CHECK: annotate-comments.cpp:274:6: FunctionDecl=comment_to_html_conversion_12:{{.*}} FullCommentAsHTML=[<dl><dt>zzz</dt><dd> Aaa.</dd></dl>]
> +// CHECK: annotate-comments.cpp:274:6: FunctionDecl=comment_to_html_conversion_12:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-invalid">zzz</dt><dd class="param-descr-index-invalid"> Aaa.</dd></dl>]
> // CHECK-NEXT: CommentAST=[
> // CHECK-NEXT: (CXComment_FullComment
> // CHECK-NEXT: (CXComment_Paragraph IsWhitespace
> @@ -499,7 +499,7 @@
> // CHECK-NEXT: (CXComment_ParamCommand in implicitly ParamName=[zzz] ParamIndex=Invalid
> // CHECK-NEXT: (CXComment_Paragraph
> // CHECK-NEXT: (CXComment_Text Text=[ Aaa.]))))]
> -// CHECK: annotate-comments.cpp:278:6: FunctionDecl=comment_to_html_conversion_13:{{.*}} FullCommentAsHTML=[<dl><dt>x1</dt><dd> Aaa.</dd><dt>x2</dt><dd> Bbb. </dd></dl>]
> +// CHECK: annotate-comments.cpp:278:6: FunctionDecl=comment_to_html_conversion_13:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-0">x1</dt><dd class="param-descr-index-0"> Aaa.</dd><dt class="param-name-index-1">x2</dt><dd class="param-descr-index-1"> Bbb. </dd></dl>]
> // CHECK-NEXT: CommentAST=[
> // CHECK-NEXT: (CXComment_FullComment
> // CHECK-NEXT: (CXComment_Paragraph IsWhitespace
> @@ -511,7 +511,7 @@
> // CHECK-NEXT: (CXComment_ParamCommand in implicitly ParamName=[x1] ParamIndex=0
> // CHECK-NEXT: (CXComment_Paragraph
> // CHECK-NEXT: (CXComment_Text Text=[ Aaa.]))))]
> -// CHECK: annotate-comments.cpp:283:6: FunctionDecl=comment_to_html_conversion_14:{{.*}} FullCommentAsHTML=[<dl><dt>x1</dt><dd> Aaa.</dd><dt>x2</dt><dd> Bbb. </dd><dt>zzz</dt><dd> Aaa. </dd></dl>]
> +// CHECK: annotate-comments.cpp:283:6: FunctionDecl=comment_to_html_conversion_14:{{.*}} FullCommentAsHTML=[<dl><dt class="param-name-index-0">x1</dt><dd class="param-descr-index-0"> Aaa.</dd><dt class="param-name-index-1">x2</dt><dd class="param-descr-index-1"> Bbb. </dd><dt class="param-name-index-invalid">zzz</dt><dd class="param-descr-index-invalid"> Aaa. </dd></dl>]
> // CHECK-NEXT: CommentAST=[
> // CHECK-NEXT: (CXComment_FullComment
> // CHECK-NEXT: (CXComment_Paragraph IsWhitespace
> @@ -527,7 +527,7 @@
> // CHECK-NEXT: (CXComment_ParamCommand in implicitly ParamName=[x1] ParamIndex=0
> // CHECK-NEXT: (CXComment_Paragraph
> // CHECK-NEXT: (CXComment_Text Text=[ Aaa.]))))]
> -// CHECK: annotate-comments.cpp:292:6: FunctionDecl=comment_to_html_conversion_15:{{.*}} FullCommentAsHTML=[<p class="para-brief"> Aaa.</p><p> Bbb.</p><dl><dt>x1</dt><dd> Ccc. </dd><dt>x2</dt><dd> Ddd. </dd></dl><p class="para-returns"><span class="word-returns">Returns</span> Eee.</p>]
> +// CHECK: annotate-comments.cpp:292:6: FunctionDecl=comment_to_html_conversion_15:{{.*}} FullCommentAsHTML=[<p class="para-brief"> Aaa.</p><p> Bbb.</p><dl><dt class="param-name-index-0">x1</dt><dd class="param-descr-index-0"> Ccc. </dd><dt class="param-name-index-1">x2</dt><dd class="param-descr-index-1"> Ddd. </dd></dl><p class="para-returns"><span class="word-returns">Returns</span> Eee.</p>]
> // CHECK-NEXT: CommentAST=[
> // CHECK-NEXT: (CXComment_FullComment
> // CHECK-NEXT: (CXComment_Paragraph IsWhitespace
> @@ -550,7 +550,7 @@
> // CHECK-NEXT: (CXComment_BlockCommand CommandName=[returns]
> // CHECK-NEXT: (CXComment_Paragraph
> // CHECK-NEXT: (CXComment_Text Text=[ Eee.]))))]
> -// CHECK: annotate-comments.cpp:295:6: FunctionDecl=comment_to_html_conversion_16:{{.*}} FullCommentAsHTML=[<p class="para-brief"> <br><a href="http://example.com/ ">Aaa</a></p>]
> +// CHECK: annotate-comments.cpp:295:6: FunctionDecl=comment_to_html_conversion_16:{{.*}} FullCommentAsHTML=[<p class="para-brief"> <br><a href="http://example.com/">Aaa</a></p>]
> // CHECK-NEXT: CommentAST=[
> // CHECK-NEXT: (CXComment_FullComment
> // CHECK-NEXT: (CXComment_Paragraph
>
> Modified: cfe/trunk/tools/libclang/CXComment.cpp
> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/tools/libclang/CXComment.cpp?rev=160595&r1=160594&r2=160595&view=diff
> ==============================================================================
> --- cfe/trunk/tools/libclang/CXComment.cpp (original)
> +++ cfe/trunk/tools/libclang/CXComment.cpp Fri Jul 20 20:47:43 2012
> @@ -18,6 +18,7 @@
> #include "clang/AST/CommentVisitor.h"
>
> #include "llvm/Support/ErrorHandling.h"
> +#include "llvm/Support/raw_ostream.h"
>
> using namespace clang;
> using namespace clang::cxstring;
> @@ -304,7 +305,8 @@
> class CommentASTToHTMLConverter :
> public ConstCommentVisitor<CommentASTToHTMLConverter> {
> public:
> - CommentASTToHTMLConverter() { }
> + /// \param Str accumulator for HTML.
> + CommentASTToHTMLConverter(SmallVectorImpl<char> &Str) : Result(Str) { }
>
> // Inline content.
> void visitTextComment(const TextComment *C);
> @@ -330,13 +332,9 @@
>
> void appendToResultWithHTMLEscaping(StringRef S);
>
> - StringRef getAsHTML() const {
> - return Result;
> - }
> -
> private:
> - /// Accumulator for converted HTML.
> - std::string Result;
> + /// Output stream for HTML.
> + llvm::raw_svector_ostream Result;
> };
> } // end unnamed namespace
>
> @@ -355,64 +353,50 @@
> if (CommandName == "b") {
> if (!HasArg0)
> return;
> - Result += "<b>";
> - Result += Arg0;
> - Result += "</b>";
> + Result << "<b>" << Arg0 << "</b>";
> return;
> }
> if (CommandName == "c" || CommandName == "p") {
> if (!HasArg0)
> return;
> - Result += "<tt>";
> - Result += Arg0;
> - Result += "</tt>";
> + Result << "<tt>" << Arg0 << "</tt>";
> return;
> }
> if (CommandName == "a" || CommandName == "e" || CommandName == "em") {
> if (!HasArg0)
> return;
> - Result += "<em>";
> - Result += Arg0;
> - Result += "</em>";
> + Result << "<em>" << Arg0 << "</em>";
> return;
> }
>
> // We don't recognize this command, so just print its arguments.
> - for (unsigned i = 0, e = C->getNumArgs(); i != e; ++i) {
> - Result += C->getArgText(i);
> - Result += " ";
> - }
> + for (unsigned i = 0, e = C->getNumArgs(); i != e; ++i)
> + Result << C->getArgText(i) << " ";
> }
>
> void CommentASTToHTMLConverter::visitHTMLStartTagComment(
> const HTMLStartTagComment *C) {
> - Result += "<";
> - Result += C->getTagName();
> + Result << "<" << C->getTagName();
>
> if (C->getNumAttrs() != 0) {
> for (unsigned i = 0, e = C->getNumAttrs(); i != e; i++) {
> - Result += " ";
> + Result << " ";
> const HTMLStartTagComment::Attribute &Attr = C->getAttr(i);
> - Result += Attr.Name;
> - if (!Attr.Value.empty()) {
> - Result += "=\"";
> - Result += Attr.Value;
> - Result += " \"";
> - }
> + Result << Attr.Name;
> + if (!Attr.Value.empty())
> + Result << "=\"" << Attr.Value << "\"";
> }
> }
>
> if (!C->isSelfClosing())
> - Result += ">";
> + Result << ">";
> else
> - Result += "/>";
> + Result << "/>";
> }
>
> void CommentASTToHTMLConverter::visitHTMLEndTagComment(
> const HTMLEndTagComment *C) {
> - Result += "</";
> - Result += C->getTagName();
> - Result += ">";
> + Result << "</" << C->getTagName() << ">";
> }
>
> void CommentASTToHTMLConverter::visitParagraphComment(
> @@ -420,28 +404,28 @@
> if (C->isWhitespace())
> return;
>
> - Result += "<p>";
> + Result << "<p>";
> for (Comment::child_iterator I = C->child_begin(), E = C->child_end();
> I != E; ++I) {
> visit(*I);
> }
> - Result += "</p>";
> + Result << "</p>";
> }
>
> void CommentASTToHTMLConverter::visitBlockCommandComment(
> const BlockCommandComment *C) {
> StringRef CommandName = C->getCommandName();
> if (CommandName == "brief" || CommandName == "short") {
> - Result += "<p class=\"para-brief\">";
> + Result << "<p class=\"para-brief\">";
> visitNonStandaloneParagraphComment(C->getParagraph());
> - Result += "</p>";
> + Result << "</p>";
> return;
> }
> if (CommandName == "returns" || CommandName == "return") {
> - Result += "<p class=\"para-returns\">";
> - Result += "<span class=\"word-returns\">Returns</span> ";
> + Result << "<p class=\"para-returns\">"
> + "<span class=\"word-returns\">Returns</span> ";
> visitNonStandaloneParagraphComment(C->getParagraph());
> - Result += "</p>";
> + Result << "</p>";
> return;
> }
> // We don't know anything about this command. Just render the paragraph.
> @@ -450,12 +434,24 @@
>
> void CommentASTToHTMLConverter::visitParamCommandComment(
> const ParamCommandComment *C) {
> - Result += "<dt>";
> - Result += C->getParamName();
> - Result += "</dt>";
> - Result += "<dd>";
> + if (C->isParamIndexValid()) {
> + Result << "<dt class=\"param-name-index-"
> + << C->getParamIndex()
> + << "\">";
> + } else
> + Result << "<dt class=\"param-name-index-invalid\">";
> +
> + Result << C->getParamName() << "</dt>";
> +
> + if (C->isParamIndexValid()) {
> + Result << "<dd class=\"param-descr-index-"
> + << C->getParamIndex()
> + << "\">";
> + } else
> + Result << "<dd class=\"param-descr-index-invalid\">";
> +
> visitNonStandaloneParagraphComment(C->getParagraph());
> - Result += "</dd>";
> + Result << "</dd>";
> }
>
> void CommentASTToHTMLConverter::visitVerbatimBlockComment(
> @@ -464,13 +460,13 @@
> if (NumLines == 0)
> return;
>
> - Result += "<pre>";
> + Result << "<pre>";
> for (unsigned i = 0; i != NumLines; ++i) {
> appendToResultWithHTMLEscaping(C->getText(i));
> if (i + 1 != NumLines)
> - Result.append("\n");
> + Result << '\n';
> }
> - Result += "</pre>";
> + Result << "</pre>";
> }
>
> void CommentASTToHTMLConverter::visitVerbatimBlockLineComment(
> @@ -480,9 +476,9 @@
>
> void CommentASTToHTMLConverter::visitVerbatimLineComment(
> const VerbatimLineComment *C) {
> - Result += "<pre>";
> + Result << "<pre>";
> appendToResultWithHTMLEscaping(C->getText());
> - Result += "</pre>";
> + Result << "</pre>";
> }
>
> void CommentASTToHTMLConverter::visitFullComment(const FullComment *C) {
> @@ -566,9 +562,9 @@
> if (Brief)
> visit(Brief);
> else if (FirstParagraph) {
> - Result += "<p class=\"para-brief\">";
> + Result << "<p class=\"para-brief\">";
> visitNonStandaloneParagraphComment(FirstParagraph);
> - Result += "</p>";
> + Result << "</p>";
> FirstParagraphIsBrief = true;
> }
>
> @@ -580,14 +576,16 @@
> }
>
> if (Params.size() != 0) {
> - Result += "<dl>";
> + Result << "<dl>";
> for (unsigned i = 0, e = Params.size(); i != e; ++i)
> visit(Params[i]);
> - Result += "</dl>";
> + Result << "</dl>";
> }
>
> if (Returns)
> visit(Returns);
> +
> + Result.flush();
> }
>
> void CommentASTToHTMLConverter::visitNonStandaloneParagraphComment(
> @@ -602,30 +600,29 @@
> }
>
> void CommentASTToHTMLConverter::appendToResultWithHTMLEscaping(StringRef S) {
> - Result.reserve(Result.size() + S.size());
> for (StringRef::iterator I = S.begin(), E = S.end(); I != E; ++I) {
> const char C = *I;
> switch (C) {
> case '&':
> - Result.append("&");
> + Result << "&";
> break;
> case '<':
> - Result.append("<");
> + Result << "<";
> break;
> case '>':
> - Result.append(">");
> + Result << ">";
> break;
> case '"':
> - Result.append(""");
> + Result << """;
> break;
> case '\'':
> - Result.append("'");
> + Result << "'";
> break;
> case '/':
> - Result.append("/");
> + Result << "/";
> break;
> default:
> - Result.push_back(C);
> + Result << C;
> break;
> }
> }
> @@ -638,9 +635,10 @@
> if (!HTC)
> return createCXString((const char *) 0);
>
> - CommentASTToHTMLConverter Converter;
> + SmallString<128> HTML;
> + CommentASTToHTMLConverter Converter(HTML);
> Converter.visit(HTC);
> - return createCXString(Converter.getAsHTML());
> + return createCXString(HTML.str(), /* DupString = */ true);
> }
>
> CXString clang_FullComment_getAsHTML(CXComment CXC) {
> @@ -648,9 +646,10 @@
> if (!FC)
> return createCXString((const char *) 0);
>
> - CommentASTToHTMLConverter Converter;
> + SmallString<1024> HTML;
> + CommentASTToHTMLConverter Converter(HTML);
> Converter.visit(FC);
> - return createCXString(Converter.getAsHTML());
> + return createCXString(HTML.str(), /* DupString = */ true);
> }
>
> } // end extern "C"
>
>
> _______________________________________________
> cfe-commits mailing list
> cfe-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
More information about the cfe-commits
mailing list