contrib/llvm/tools/clang/lib/Index/CommentToXML.cpp

   1 //===--- CommentToXML.cpp - Convert comments to XML representation --------===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #include "clang/Index/CommentToXML.h"
  11 #include "clang/AST/ASTContext.h"
  12 #include "clang/AST/Attr.h"
  13 #include "clang/AST/Comment.h"
  14 #include "clang/AST/CommentVisitor.h"
  15 #include "clang/Format/Format.h"
  16 #include "clang/Index/USRGeneration.h"
  17 #include "llvm/ADT/StringExtras.h"
  18 #include "llvm/ADT/TinyPtrVector.h"
  19 #include "llvm/Support/raw_ostream.h"
  20
  21 using namespace clang;
  22 using namespace clang::comments;
  23 using namespace clang::index;
  24
  25 namespace {
  26
  27 /// This comparison will sort parameters with valid index by index, then vararg
  28 /// parameters, and invalid (unresolved) parameters last.
  29 class ParamCommandCommentCompareIndex {
  30 public:
  31   bool operator()(const ParamCommandComment *LHS,
  32                   const ParamCommandComment *RHS) const {
  33     unsigned LHSIndex = UINT_MAX;
  34     unsigned RHSIndex = UINT_MAX;
  35
  36     if (LHS->isParamIndexValid()) {
  37       if (LHS->isVarArgParam())
  38         LHSIndex = UINT_MAX - 1;
  39       else
  40         LHSIndex = LHS->getParamIndex();
  41     }
  42     if (RHS->isParamIndexValid()) {
  43       if (RHS->isVarArgParam())
  44         RHSIndex = UINT_MAX - 1;
  45       else
  46         RHSIndex = RHS->getParamIndex();
  47     }
  48     return LHSIndex < RHSIndex;
  49   }
  50 };
  51
  52 /// This comparison will sort template parameters in the following order:
  53 /// \li real template parameters (depth = 1) in index order;
  54 /// \li all other names (depth > 1);
  55 /// \li unresolved names.
  56 class TParamCommandCommentComparePosition {
  57 public:
  58   bool operator()(const TParamCommandComment *LHS,
  59                   const TParamCommandComment *RHS) const {
  60     // Sort unresolved names last.
  61     if (!LHS->isPositionValid())
  62       return false;
  63     if (!RHS->isPositionValid())
  64       return true;
  65
  66     if (LHS->getDepth() > 1)
  67       return false;
  68     if (RHS->getDepth() > 1)
  69       return true;
  70
  71     // Sort template parameters in index order.
  72     if (LHS->getDepth() == 1 && RHS->getDepth() == 1)
  73       return LHS->getIndex(0) < RHS->getIndex(0);
  74
  75     // Leave all other names in source order.
  76     return true;
  77   }
  78 };
  79
  80 /// Separate parts of a FullComment.
  81 struct FullCommentParts {
  82   /// Take a full comment apart and initialize members accordingly.
  83   FullCommentParts(const FullComment *C,
  84                    const CommandTraits &Traits);
  85
  86   const BlockContentComment *Brief;
  87   const BlockContentComment *Headerfile;
  88   const ParagraphComment *FirstParagraph;
  89   SmallVector<const BlockCommandComment *, 4> Returns;
  90   SmallVector<const ParamCommandComment *, 8> Params;
  91   SmallVector<const TParamCommandComment *, 4> TParams;
  92   llvm::TinyPtrVector<const BlockCommandComment *> Exceptions;
  93   SmallVector<const BlockContentComment *, 8> MiscBlocks;
  94 };
  95
  96 FullCommentParts::FullCommentParts(const FullComment *C,
  97                                    const CommandTraits &Traits) :
  98     Brief(nullptr), Headerfile(nullptr), FirstParagraph(nullptr) {
  99   for (Comment::child_iterator I = C->child_begin(), E = C->child_end();
 100        I != E; ++I) {
 101     const Comment *Child = *I;
 102     if (!Child)
 103       continue;
 104     switch (Child->getCommentKind()) {
 105     case Comment::NoCommentKind:
 106       continue;
 107
 108     case Comment::ParagraphCommentKind: {
 109       const ParagraphComment *PC = cast<ParagraphComment>(Child);
 110       if (PC->isWhitespace())
 111         break;
 112       if (!FirstParagraph)
 113         FirstParagraph = PC;
 114
 115       MiscBlocks.push_back(PC);
 116       break;
 117     }
 118
 119     case Comment::BlockCommandCommentKind: {
 120       const BlockCommandComment *BCC = cast<BlockCommandComment>(Child);
 121       const CommandInfo *Info = Traits.getCommandInfo(BCC->getCommandID());
 122       if (!Brief && Info->IsBriefCommand) {
 123         Brief = BCC;
 124         break;
 125       }
 126       if (!Headerfile && Info->IsHeaderfileCommand) {
 127         Headerfile = BCC;
 128         break;
 129       }
 130       if (Info->IsReturnsCommand) {
 131         Returns.push_back(BCC);
 132         break;
 133       }
 134       if (Info->IsThrowsCommand) {
 135         Exceptions.push_back(BCC);
 136         break;
 137       }
 138       MiscBlocks.push_back(BCC);
 139       break;
 140     }
 141
 142     case Comment::ParamCommandCommentKind: {
 143       const ParamCommandComment *PCC = cast<ParamCommandComment>(Child);
 144       if (!PCC->hasParamName())
 145         break;
 146
 147       if (!PCC->isDirectionExplicit() && !PCC->hasNonWhitespaceParagraph())
 148         break;
 149
 150       Params.push_back(PCC);
 151       break;
 152     }
 153
 154     case Comment::TParamCommandCommentKind: {
 155       const TParamCommandComment *TPCC = cast<TParamCommandComment>(Child);
 156       if (!TPCC->hasParamName())
 157         break;
 158
 159       if (!TPCC->hasNonWhitespaceParagraph())
 160         break;
 161
 162       TParams.push_back(TPCC);
 163       break;
 164     }
 165
 166     case Comment::VerbatimBlockCommentKind:
 167       MiscBlocks.push_back(cast<BlockCommandComment>(Child));
 168       break;
 169
 170     case Comment::VerbatimLineCommentKind: {
 171       const VerbatimLineComment *VLC = cast<VerbatimLineComment>(Child);
 172       const CommandInfo *Info = Traits.getCommandInfo(VLC->getCommandID());
 173       if (!Info->IsDeclarationCommand)
 174         MiscBlocks.push_back(VLC);
 175       break;
 176     }
 177
 178     case Comment::TextCommentKind:
 179     case Comment::InlineCommandCommentKind:
 180     case Comment::HTMLStartTagCommentKind:
 181     case Comment::HTMLEndTagCommentKind:
 182     case Comment::VerbatimBlockLineCommentKind:
 183     case Comment::FullCommentKind:
 184       llvm_unreachable("AST node of this kind can't be a child of "
 185                        "a FullComment");
 186     }
 187   }
 188
 189   // Sort params in order they are declared in the function prototype.
 190   // Unresolved parameters are put at the end of the list in the same order
 191   // they were seen in the comment.
 192   std::stable_sort(Params.begin(), Params.end(),
 193                    ParamCommandCommentCompareIndex());
 194
 195   std::stable_sort(TParams.begin(), TParams.end(),
 196                    TParamCommandCommentComparePosition());
 197 }
 198
 199 void printHTMLStartTagComment(const HTMLStartTagComment *C,
 200                               llvm::raw_svector_ostream &Result) {
 201   Result << "<" << C->getTagName();
 202
 203   if (C->getNumAttrs() != 0) {
 204     for (unsigned i = 0, e = C->getNumAttrs(); i != e; i++) {
 205       Result << " ";
 206       const HTMLStartTagComment::Attribute &Attr = C->getAttr(i);
 207       Result << Attr.Name;
 208       if (!Attr.Value.empty())
 209         Result << "=\"" << Attr.Value << "\"";
 210     }
 211   }
 212
 213   if (!C->isSelfClosing())
 214     Result << ">";
 215   else
 216     Result << "/>";
 217 }
 218
 219 class CommentASTToHTMLConverter :
 220     public ConstCommentVisitor<CommentASTToHTMLConverter> {
 221 public:
 222   /// \param Str accumulator for HTML.
 223   CommentASTToHTMLConverter(const FullComment *FC,
 224                             SmallVectorImpl<char> &Str,
 225                             const CommandTraits &Traits) :
 226       FC(FC), Result(Str), Traits(Traits)
 227   { }
 228
 229   // Inline content.
 230   void visitTextComment(const TextComment *C);
 231   void visitInlineCommandComment(const InlineCommandComment *C);
 232   void visitHTMLStartTagComment(const HTMLStartTagComment *C);
 233   void visitHTMLEndTagComment(const HTMLEndTagComment *C);
 234
 235   // Block content.
 236   void visitParagraphComment(const ParagraphComment *C);
 237   void visitBlockCommandComment(const BlockCommandComment *C);
 238   void visitParamCommandComment(const ParamCommandComment *C);
 239   void visitTParamCommandComment(const TParamCommandComment *C);
 240   void visitVerbatimBlockComment(const VerbatimBlockComment *C);
 241   void visitVerbatimBlockLineComment(const VerbatimBlockLineComment *C);
 242   void visitVerbatimLineComment(const VerbatimLineComment *C);
 243
 244   void visitFullComment(const FullComment *C);
 245
 246   // Helpers.
 247
 248   /// Convert a paragraph that is not a block by itself (an argument to some
 249   /// command).
 250   void visitNonStandaloneParagraphComment(const ParagraphComment *C);
 251
 252   void appendToResultWithHTMLEscaping(StringRef S);
 253
 254 private:
 255   const FullComment *FC;
 256   /// Output stream for HTML.
 257   llvm::raw_svector_ostream Result;
 258
 259   const CommandTraits &Traits;
 260 };
 261 } // end unnamed namespace
 262
 263 void CommentASTToHTMLConverter::visitTextComment(const TextComment *C) {
 264   appendToResultWithHTMLEscaping(C->getText());
 265 }
 266
 267 void CommentASTToHTMLConverter::visitInlineCommandComment(
 268                                   const InlineCommandComment *C) {
 269   // Nothing to render if no arguments supplied.
 270   if (C->getNumArgs() == 0)
 271     return;
 272
 273   // Nothing to render if argument is empty.
 274   StringRef Arg0 = C->getArgText(0);
 275   if (Arg0.empty())
 276     return;
 277
 278   switch (C->getRenderKind()) {
 279   case InlineCommandComment::RenderNormal:
 280     for (unsigned i = 0, e = C->getNumArgs(); i != e; ++i) {
 281       appendToResultWithHTMLEscaping(C->getArgText(i));
 282       Result << " ";
 283     }
 284     return;
 285
 286   case InlineCommandComment::RenderBold:
 287     assert(C->getNumArgs() == 1);
 288     Result << "<b>";
 289     appendToResultWithHTMLEscaping(Arg0);
 290     Result << "</b>";
 291     return;
 292   case InlineCommandComment::RenderMonospaced:
 293     assert(C->getNumArgs() == 1);
 294     Result << "<tt>";
 295     appendToResultWithHTMLEscaping(Arg0);
 296     Result<< "</tt>";
 297     return;
 298   case InlineCommandComment::RenderEmphasized:
 299     assert(C->getNumArgs() == 1);
 300     Result << "<em>";
 301     appendToResultWithHTMLEscaping(Arg0);
 302     Result << "</em>";
 303     return;
 304   }
 305 }
 306
 307 void CommentASTToHTMLConverter::visitHTMLStartTagComment(
 308                                   const HTMLStartTagComment *C) {
 309   printHTMLStartTagComment(C, Result);
 310 }
 311
 312 void CommentASTToHTMLConverter::visitHTMLEndTagComment(
 313                                   const HTMLEndTagComment *C) {
 314   Result << "</" << C->getTagName() << ">";
 315 }
 316
 317 void CommentASTToHTMLConverter::visitParagraphComment(
 318                                   const ParagraphComment *C) {
 319   if (C->isWhitespace())
 320     return;
 321
 322   Result << "<p>";
 323   for (Comment::child_iterator I = C->child_begin(), E = C->child_end();
 324        I != E; ++I) {
 325     visit(*I);
 326   }
 327   Result << "</p>";
 328 }
 329
 330 void CommentASTToHTMLConverter::visitBlockCommandComment(
 331                                   const BlockCommandComment *C) {
 332   const CommandInfo *Info = Traits.getCommandInfo(C->getCommandID());
 333   if (Info->IsBriefCommand) {
 334     Result << "<p class=\"para-brief\">";
 335     visitNonStandaloneParagraphComment(C->getParagraph());
 336     Result << "</p>";
 337     return;
 338   }
 339   if (Info->IsReturnsCommand) {
 340     Result << "<p class=\"para-returns\">"
 341               "<span class=\"word-returns\">Returns</span> ";
 342     visitNonStandaloneParagraphComment(C->getParagraph());
 343     Result << "</p>";
 344     return;
 345   }
 346   // We don't know anything about this command.  Just render the paragraph.
 347   visit(C->getParagraph());
 348 }
 349
 350 void CommentASTToHTMLConverter::visitParamCommandComment(
 351                                   const ParamCommandComment *C) {
 352   if (C->isParamIndexValid()) {
 353     if (C->isVarArgParam()) {
 354       Result << "<dt class=\"param-name-index-vararg\">";
 355       appendToResultWithHTMLEscaping(C->getParamNameAsWritten());
 356     } else {
 357       Result << "<dt class=\"param-name-index-"
 358              << C->getParamIndex()
 359              << "\">";
 360       appendToResultWithHTMLEscaping(C->getParamName(FC));
 361     }
 362   } else {
 363     Result << "<dt class=\"param-name-index-invalid\">";
 364     appendToResultWithHTMLEscaping(C->getParamNameAsWritten());
 365   }
 366   Result << "</dt>";
 367
 368   if (C->isParamIndexValid()) {
 369     if (C->isVarArgParam())
 370       Result << "<dd class=\"param-descr-index-vararg\">";
 371     else
 372       Result << "<dd class=\"param-descr-index-"
 373              << C->getParamIndex()
 374              << "\">";
 375   } else
 376     Result << "<dd class=\"param-descr-index-invalid\">";
 377
 378   visitNonStandaloneParagraphComment(C->getParagraph());
 379   Result << "</dd>";
 380 }
 381
 382 void CommentASTToHTMLConverter::visitTParamCommandComment(
 383                                   const TParamCommandComment *C) {
 384   if (C->isPositionValid()) {
 385     if (C->getDepth() == 1)
 386       Result << "<dt class=\"tparam-name-index-"
 387              << C->getIndex(0)
 388              << "\">";
 389     else
 390       Result << "<dt class=\"tparam-name-index-other\">";
 391     appendToResultWithHTMLEscaping(C->getParamName(FC));
 392   } else {
 393     Result << "<dt class=\"tparam-name-index-invalid\">";
 394     appendToResultWithHTMLEscaping(C->getParamNameAsWritten());
 395   }
 396
 397   Result << "</dt>";
 398
 399   if (C->isPositionValid()) {
 400     if (C->getDepth() == 1)
 401       Result << "<dd class=\"tparam-descr-index-"
 402              << C->getIndex(0)
 403              << "\">";
 404     else
 405       Result << "<dd class=\"tparam-descr-index-other\">";
 406   } else
 407     Result << "<dd class=\"tparam-descr-index-invalid\">";
 408
 409   visitNonStandaloneParagraphComment(C->getParagraph());
 410   Result << "</dd>";
 411 }
 412
 413 void CommentASTToHTMLConverter::visitVerbatimBlockComment(
 414                                   const VerbatimBlockComment *C) {
 415   unsigned NumLines = C->getNumLines();
 416   if (NumLines == 0)
 417     return;
 418
 419   Result << "<pre>";
 420   for (unsigned i = 0; i != NumLines; ++i) {
 421     appendToResultWithHTMLEscaping(C->getText(i));
 422     if (i + 1 != NumLines)
 423       Result << '\n';
 424   }
 425   Result << "</pre>";
 426 }
 427
 428 void CommentASTToHTMLConverter::visitVerbatimBlockLineComment(
 429                                   const VerbatimBlockLineComment *C) {
 430   llvm_unreachable("should not see this AST node");
 431 }
 432
 433 void CommentASTToHTMLConverter::visitVerbatimLineComment(
 434                                   const VerbatimLineComment *C) {
 435   Result << "<pre>";
 436   appendToResultWithHTMLEscaping(C->getText());
 437   Result << "</pre>";
 438 }
 439
 440 void CommentASTToHTMLConverter::visitFullComment(const FullComment *C) {
 441   FullCommentParts Parts(C, Traits);
 442
 443   bool FirstParagraphIsBrief = false;
 444   if (Parts.Headerfile)
 445     visit(Parts.Headerfile);
 446   if (Parts.Brief)
 447     visit(Parts.Brief);
 448   else if (Parts.FirstParagraph) {
 449     Result << "<p class=\"para-brief\">";
 450     visitNonStandaloneParagraphComment(Parts.FirstParagraph);
 451     Result << "</p>";
 452     FirstParagraphIsBrief = true;
 453   }
 454
 455   for (unsigned i = 0, e = Parts.MiscBlocks.size(); i != e; ++i) {
 456     const Comment *C = Parts.MiscBlocks[i];
 457     if (FirstParagraphIsBrief && C == Parts.FirstParagraph)
 458       continue;
 459     visit(C);
 460   }
 461
 462   if (Parts.TParams.size() != 0) {
 463     Result << "<dl>";
 464     for (unsigned i = 0, e = Parts.TParams.size(); i != e; ++i)
 465       visit(Parts.TParams[i]);
 466     Result << "</dl>";
 467   }
 468
 469   if (Parts.Params.size() != 0) {
 470     Result << "<dl>";
 471     for (unsigned i = 0, e = Parts.Params.size(); i != e; ++i)
 472       visit(Parts.Params[i]);
 473     Result << "</dl>";
 474   }
 475
 476   if (Parts.Returns.size() != 0) {
 477     Result << "<div class=\"result-discussion\">";
 478     for (unsigned i = 0, e = Parts.Returns.size(); i != e; ++i)
 479       visit(Parts.Returns[i]);
 480     Result << "</div>";
 481   }
 482
 483 }
 484
 485 void CommentASTToHTMLConverter::visitNonStandaloneParagraphComment(
 486                                   const ParagraphComment *C) {
 487   if (!C)
 488     return;
 489
 490   for (Comment::child_iterator I = C->child_begin(), E = C->child_end();
 491        I != E; ++I) {
 492     visit(*I);
 493   }
 494 }
 495
 496 void CommentASTToHTMLConverter::appendToResultWithHTMLEscaping(StringRef S) {
 497   for (StringRef::iterator I = S.begin(), E = S.end(); I != E; ++I) {
 498     const char C = *I;
 499     switch (C) {
 500     case '&':
 501       Result << "&amp;";
 502       break;
 503     case '<':
 504       Result << "&lt;";
 505       break;
 506     case '>':
 507       Result << "&gt;";
 508       break;
 509     case '"':
 510       Result << "&quot;";
 511       break;
 512     case '\'':
 513       Result << "&#39;";
 514       break;
 515     case '/':
 516       Result << "&#47;";
 517       break;
 518     default:
 519       Result << C;
 520       break;
 521     }
 522   }
 523 }
 524
 525 namespace {
 526 class CommentASTToXMLConverter :
 527     public ConstCommentVisitor<CommentASTToXMLConverter> {
 528 public:
 529   /// \param Str accumulator for XML.
 530   CommentASTToXMLConverter(const FullComment *FC,
 531                            SmallVectorImpl<char> &Str,
 532                            const CommandTraits &Traits,
 533                            const SourceManager &SM) :
 534       FC(FC), Result(Str), Traits(Traits), SM(SM) { }
 535
 536   // Inline content.
 537   void visitTextComment(const TextComment *C);
 538   void visitInlineCommandComment(const InlineCommandComment *C);
 539   void visitHTMLStartTagComment(const HTMLStartTagComment *C);
 540   void visitHTMLEndTagComment(const HTMLEndTagComment *C);
 541
 542   // Block content.
 543   void visitParagraphComment(const ParagraphComment *C);
 544
 545   void appendParagraphCommentWithKind(const ParagraphComment *C,
 546                                       StringRef Kind);
 547
 548   void visitBlockCommandComment(const BlockCommandComment *C);
 549   void visitParamCommandComment(const ParamCommandComment *C);
 550   void visitTParamCommandComment(const TParamCommandComment *C);
 551   void visitVerbatimBlockComment(const VerbatimBlockComment *C);
 552   void visitVerbatimBlockLineComment(const VerbatimBlockLineComment *C);
 553   void visitVerbatimLineComment(const VerbatimLineComment *C);
 554
 555   void visitFullComment(const FullComment *C);
 556
 557   // Helpers.
 558   void appendToResultWithXMLEscaping(StringRef S);
 559   void appendToResultWithCDATAEscaping(StringRef S);
 560
 561   void formatTextOfDeclaration(const DeclInfo *DI,
 562                                SmallString<128> &Declaration);
 563
 564 private:
 565   const FullComment *FC;
 566
 567   /// Output stream for XML.
 568   llvm::raw_svector_ostream Result;
 569
 570   const CommandTraits &Traits;
 571   const SourceManager &SM;
 572 };
 573
 574 void getSourceTextOfDeclaration(const DeclInfo *ThisDecl,
 575                                 SmallVectorImpl<char> &Str) {
 576   ASTContext &Context = ThisDecl->CurrentDecl->getASTContext();
 577   const LangOptions &LangOpts = Context.getLangOpts();
 578   llvm::raw_svector_ostream OS(Str);
 579   PrintingPolicy PPolicy(LangOpts);
 580   PPolicy.PolishForDeclaration = true;
 581   PPolicy.TerseOutput = true;
 582   ThisDecl->CurrentDecl->print(OS, PPolicy,
 583                                /*Indentation*/0, /*PrintInstantiation*/false);
 584 }
 585
 586 void CommentASTToXMLConverter::formatTextOfDeclaration(
 587     const DeclInfo *DI, SmallString<128> &Declaration) {
 588   // Formatting API expects null terminated input string.
 589   StringRef StringDecl(Declaration.c_str(), Declaration.size());
 590
 591   // Formatter specific code.
 592   unsigned Offset = 0;
 593   unsigned Length = Declaration.size();
 594
 595   format::FormatStyle Style = format::getLLVMStyle();
 596   Style.FixNamespaceComments = false;
 597   tooling::Replacements Replaces =
 598       reformat(Style, StringDecl, tooling::Range(Offset, Length), "xmldecl.xd");
 599   auto FormattedStringDecl = applyAllReplacements(StringDecl, Replaces);
 600   if (static_cast<bool>(FormattedStringDecl)) {
 601     Declaration = *FormattedStringDecl;
 602   }
 603 }
 604
 605 } // end unnamed namespace
 606
 607 void CommentASTToXMLConverter::visitTextComment(const TextComment *C) {
 608   appendToResultWithXMLEscaping(C->getText());
 609 }
 610
 611 void CommentASTToXMLConverter::visitInlineCommandComment(
 612     const InlineCommandComment *C) {
 613   // Nothing to render if no arguments supplied.
 614   if (C->getNumArgs() == 0)
 615     return;
 616
 617   // Nothing to render if argument is empty.
 618   StringRef Arg0 = C->getArgText(0);
 619   if (Arg0.empty())
 620     return;
 621
 622   switch (C->getRenderKind()) {
 623   case InlineCommandComment::RenderNormal:
 624     for (unsigned i = 0, e = C->getNumArgs(); i != e; ++i) {
 625       appendToResultWithXMLEscaping(C->getArgText(i));
 626       Result << " ";
 627     }
 628     return;
 629   case InlineCommandComment::RenderBold:
 630     assert(C->getNumArgs() == 1);
 631     Result << "<bold>";
 632     appendToResultWithXMLEscaping(Arg0);
 633     Result << "</bold>";
 634     return;
 635   case InlineCommandComment::RenderMonospaced:
 636     assert(C->getNumArgs() == 1);
 637     Result << "<monospaced>";
 638     appendToResultWithXMLEscaping(Arg0);
 639     Result << "</monospaced>";
 640     return;
 641   case InlineCommandComment::RenderEmphasized:
 642     assert(C->getNumArgs() == 1);
 643     Result << "<emphasized>";
 644     appendToResultWithXMLEscaping(Arg0);
 645     Result << "</emphasized>";
 646     return;
 647   }
 648 }
 649
 650 void CommentASTToXMLConverter::visitHTMLStartTagComment(
 651     const HTMLStartTagComment *C) {
 652   Result << "<rawHTML";
 653   if (C->isMalformed())
 654     Result << " isMalformed=\"1\"";
 655   Result << ">";
 656   {
 657     SmallString<32> Tag;
 658     {
 659       llvm::raw_svector_ostream TagOS(Tag);
 660       printHTMLStartTagComment(C, TagOS);
 661     }
 662     appendToResultWithCDATAEscaping(Tag);
 663   }
 664   Result << "</rawHTML>";
 665 }
 666
 667 void
 668 CommentASTToXMLConverter::visitHTMLEndTagComment(const HTMLEndTagComment *C) {
 669   Result << "<rawHTML";
 670   if (C->isMalformed())
 671     Result << " isMalformed=\"1\"";
 672   Result << ">&lt;/" << C->getTagName() << "&gt;</rawHTML>";
 673 }
 674
 675 void
 676 CommentASTToXMLConverter::visitParagraphComment(const ParagraphComment *C) {
 677   appendParagraphCommentWithKind(C, StringRef());
 678 }
 679
 680 void CommentASTToXMLConverter::appendParagraphCommentWithKind(
 681                                   const ParagraphComment *C,
 682                                   StringRef ParagraphKind) {
 683   if (C->isWhitespace())
 684     return;
 685
 686   if (ParagraphKind.empty())
 687     Result << "<Para>";
 688   else
 689     Result << "<Para kind=\"" << ParagraphKind << "\">";
 690
 691   for (Comment::child_iterator I = C->child_begin(), E = C->child_end();
 692        I != E; ++I) {
 693     visit(*I);
 694   }
 695   Result << "</Para>";
 696 }
 697
 698 void CommentASTToXMLConverter::visitBlockCommandComment(
 699     const BlockCommandComment *C) {
 700   StringRef ParagraphKind;
 701
 702   switch (C->getCommandID()) {
 703   case CommandTraits::KCI_attention:
 704   case CommandTraits::KCI_author:
 705   case CommandTraits::KCI_authors:
 706   case CommandTraits::KCI_bug:
 707   case CommandTraits::KCI_copyright:
 708   case CommandTraits::KCI_date:
 709   case CommandTraits::KCI_invariant:
 710   case CommandTraits::KCI_note:
 711   case CommandTraits::KCI_post:
 712   case CommandTraits::KCI_pre:
 713   case CommandTraits::KCI_remark:
 714   case CommandTraits::KCI_remarks:
 715   case CommandTraits::KCI_sa:
 716   case CommandTraits::KCI_see:
 717   case CommandTraits::KCI_since:
 718   case CommandTraits::KCI_todo:
 719   case CommandTraits::KCI_version:
 720   case CommandTraits::KCI_warning:
 721     ParagraphKind = C->getCommandName(Traits);
 722   default:
 723     break;
 724   }
 725
 726   appendParagraphCommentWithKind(C->getParagraph(), ParagraphKind);
 727 }
 728
 729 void CommentASTToXMLConverter::visitParamCommandComment(
 730     const ParamCommandComment *C) {
 731   Result << "<Parameter><Name>";
 732   appendToResultWithXMLEscaping(C->isParamIndexValid()
 733                                     ? C->getParamName(FC)
 734                                     : C->getParamNameAsWritten());
 735   Result << "</Name>";
 736
 737   if (C->isParamIndexValid()) {
 738     if (C->isVarArgParam())
 739       Result << "<IsVarArg />";
 740     else
 741       Result << "<Index>" << C->getParamIndex() << "</Index>";
 742   }
 743
 744   Result << "<Direction isExplicit=\"" << C->isDirectionExplicit() << "\">";
 745   switch (C->getDirection()) {
 746   case ParamCommandComment::In:
 747     Result << "in";
 748     break;
 749   case ParamCommandComment::Out:
 750     Result << "out";
 751     break;
 752   case ParamCommandComment::InOut:
 753     Result << "in,out";
 754     break;
 755   }
 756   Result << "</Direction><Discussion>";
 757   visit(C->getParagraph());
 758   Result << "</Discussion></Parameter>";
 759 }
 760
 761 void CommentASTToXMLConverter::visitTParamCommandComment(
 762                                   const TParamCommandComment *C) {
 763   Result << "<Parameter><Name>";
 764   appendToResultWithXMLEscaping(C->isPositionValid() ? C->getParamName(FC)
 765                                 : C->getParamNameAsWritten());
 766   Result << "</Name>";
 767
 768   if (C->isPositionValid() && C->getDepth() == 1) {
 769     Result << "<Index>" << C->getIndex(0) << "</Index>";
 770   }
 771
 772   Result << "<Discussion>";
 773   visit(C->getParagraph());
 774   Result << "</Discussion></Parameter>";
 775 }
 776
 777 void CommentASTToXMLConverter::visitVerbatimBlockComment(
 778                                   const VerbatimBlockComment *C) {
 779   unsigned NumLines = C->getNumLines();
 780   if (NumLines == 0)
 781     return;
 782
 783   switch (C->getCommandID()) {
 784   case CommandTraits::KCI_code:
 785     Result << "<Verbatim xml:space=\"preserve\" kind=\"code\">";
 786     break;
 787   default:
 788     Result << "<Verbatim xml:space=\"preserve\" kind=\"verbatim\">";
 789     break;
 790   }
 791   for (unsigned i = 0; i != NumLines; ++i) {
 792     appendToResultWithXMLEscaping(C->getText(i));
 793     if (i + 1 != NumLines)
 794       Result << '\n';
 795   }
 796   Result << "</Verbatim>";
 797 }
 798
 799 void CommentASTToXMLConverter::visitVerbatimBlockLineComment(
 800                                   const VerbatimBlockLineComment *C) {
 801   llvm_unreachable("should not see this AST node");
 802 }
 803
 804 void CommentASTToXMLConverter::visitVerbatimLineComment(
 805                                   const VerbatimLineComment *C) {
 806   Result << "<Verbatim xml:space=\"preserve\" kind=\"verbatim\">";
 807   appendToResultWithXMLEscaping(C->getText());
 808   Result << "</Verbatim>";
 809 }
 810
 811 void CommentASTToXMLConverter::visitFullComment(const FullComment *C) {
 812   FullCommentParts Parts(C, Traits);
 813
 814   const DeclInfo *DI = C->getDeclInfo();
 815   StringRef RootEndTag;
 816   if (DI) {
 817     switch (DI->getKind()) {
 818     case DeclInfo::OtherKind:
 819       RootEndTag = "</Other>";
 820       Result << "<Other";
 821       break;
 822     case DeclInfo::FunctionKind:
 823       RootEndTag = "</Function>";
 824       Result << "<Function";
 825       switch (DI->TemplateKind) {
 826       case DeclInfo::NotTemplate:
 827         break;
 828       case DeclInfo::Template:
 829         Result << " templateKind=\"template\"";
 830         break;
 831       case DeclInfo::TemplateSpecialization:
 832         Result << " templateKind=\"specialization\"";
 833         break;
 834       case DeclInfo::TemplatePartialSpecialization:
 835         llvm_unreachable("partial specializations of functions "
 836                          "are not allowed in C++");
 837       }
 838       if (DI->IsInstanceMethod)
 839         Result << " isInstanceMethod=\"1\"";
 840       if (DI->IsClassMethod)
 841         Result << " isClassMethod=\"1\"";
 842       break;
 843     case DeclInfo::ClassKind:
 844       RootEndTag = "</Class>";
 845       Result << "<Class";
 846       switch (DI->TemplateKind) {
 847       case DeclInfo::NotTemplate:
 848         break;
 849       case DeclInfo::Template:
 850         Result << " templateKind=\"template\"";
 851         break;
 852       case DeclInfo::TemplateSpecialization:
 853         Result << " templateKind=\"specialization\"";
 854         break;
 855       case DeclInfo::TemplatePartialSpecialization:
 856         Result << " templateKind=\"partialSpecialization\"";
 857         break;
 858       }
 859       break;
 860     case DeclInfo::VariableKind:
 861       RootEndTag = "</Variable>";
 862       Result << "<Variable";
 863       break;
 864     case DeclInfo::NamespaceKind:
 865       RootEndTag = "</Namespace>";
 866       Result << "<Namespace";
 867       break;
 868     case DeclInfo::TypedefKind:
 869       RootEndTag = "</Typedef>";
 870       Result << "<Typedef";
 871       break;
 872     case DeclInfo::EnumKind:
 873       RootEndTag = "</Enum>";
 874       Result << "<Enum";
 875       break;
 876     }
 877
 878     {
 879       // Print line and column number.
 880       SourceLocation Loc = DI->CurrentDecl->getLocation();
 881       std::pair<FileID, unsigned> LocInfo = SM.getDecomposedLoc(Loc);
 882       FileID FID = LocInfo.first;
 883       unsigned FileOffset = LocInfo.second;
 884
 885       if (FID.isValid()) {
 886         if (const FileEntry *FE = SM.getFileEntryForID(FID)) {
 887           Result << " file=\"";
 888           appendToResultWithXMLEscaping(FE->getName());
 889           Result << "\"";
 890         }
 891         Result << " line=\"" << SM.getLineNumber(FID, FileOffset)
 892                << "\" column=\"" << SM.getColumnNumber(FID, FileOffset)
 893                << "\"";
 894       }
 895     }
 896
 897     // Finish the root tag.
 898     Result << ">";
 899
 900     bool FoundName = false;
 901     if (const NamedDecl *ND = dyn_cast<NamedDecl>(DI->CommentDecl)) {
 902       if (DeclarationName DeclName = ND->getDeclName()) {
 903         Result << "<Name>";
 904         std::string Name = DeclName.getAsString();
 905         appendToResultWithXMLEscaping(Name);
 906         FoundName = true;
 907         Result << "</Name>";
 908       }
 909     }
 910     if (!FoundName)
 911       Result << "<Name>&lt;anonymous&gt;</Name>";
 912
 913     {
 914       // Print USR.
 915       SmallString<128> USR;
 916       generateUSRForDecl(DI->CommentDecl, USR);
 917       if (!USR.empty()) {
 918         Result << "<USR>";
 919         appendToResultWithXMLEscaping(USR);
 920         Result << "</USR>";
 921       }
 922     }
 923   } else {
 924     // No DeclInfo -- just emit some root tag and name tag.
 925     RootEndTag = "</Other>";
 926     Result << "<Other><Name>unknown</Name>";
 927   }
 928
 929   if (Parts.Headerfile) {
 930     Result << "<Headerfile>";
 931     visit(Parts.Headerfile);
 932     Result << "</Headerfile>";
 933   }
 934
 935   {
 936     // Pretty-print the declaration.
 937     Result << "<Declaration>";
 938     SmallString<128> Declaration;
 939     getSourceTextOfDeclaration(DI, Declaration);
 940     formatTextOfDeclaration(DI, Declaration);
 941     appendToResultWithXMLEscaping(Declaration);
 942     Result << "</Declaration>";
 943   }
 944
 945   bool FirstParagraphIsBrief = false;
 946   if (Parts.Brief) {
 947     Result << "<Abstract>";
 948     visit(Parts.Brief);
 949     Result << "</Abstract>";
 950   } else if (Parts.FirstParagraph) {
 951     Result << "<Abstract>";
 952     visit(Parts.FirstParagraph);
 953     Result << "</Abstract>";
 954     FirstParagraphIsBrief = true;
 955   }
 956
 957   if (Parts.TParams.size() != 0) {
 958     Result << "<TemplateParameters>";
 959     for (unsigned i = 0, e = Parts.TParams.size(); i != e; ++i)
 960       visit(Parts.TParams[i]);
 961     Result << "</TemplateParameters>";
 962   }
 963
 964   if (Parts.Params.size() != 0) {
 965     Result << "<Parameters>";
 966     for (unsigned i = 0, e = Parts.Params.size(); i != e; ++i)
 967       visit(Parts.Params[i]);
 968     Result << "</Parameters>";
 969   }
 970
 971   if (Parts.Exceptions.size() != 0) {
 972     Result << "<Exceptions>";
 973     for (unsigned i = 0, e = Parts.Exceptions.size(); i != e; ++i)
 974       visit(Parts.Exceptions[i]);
 975     Result << "</Exceptions>";
 976   }
 977
 978   if (Parts.Returns.size() != 0) {
 979     Result << "<ResultDiscussion>";
 980     for (unsigned i = 0, e = Parts.Returns.size(); i != e; ++i)
 981       visit(Parts.Returns[i]);
 982     Result << "</ResultDiscussion>";
 983   }
 984
 985   if (DI->CommentDecl->hasAttrs()) {
 986     const AttrVec &Attrs = DI->CommentDecl->getAttrs();
 987     for (unsigned i = 0, e = Attrs.size(); i != e; i++) {
 988       const AvailabilityAttr *AA = dyn_cast<AvailabilityAttr>(Attrs[i]);
 989       if (!AA) {
 990         if (const DeprecatedAttr *DA = dyn_cast<DeprecatedAttr>(Attrs[i])) {
 991           if (DA->getMessage().empty())
 992             Result << "<Deprecated/>";
 993           else {
 994             Result << "<Deprecated>";
 995             appendToResultWithXMLEscaping(DA->getMessage());
 996             Result << "</Deprecated>";
 997           }
 998         }
 999         else if (const UnavailableAttr *UA = dyn_cast<UnavailableAttr>(Attrs[i])) {
1000           if (UA->getMessage().empty())
1001             Result << "<Unavailable/>";
1002           else {
1003             Result << "<Unavailable>";
1004             appendToResultWithXMLEscaping(UA->getMessage());
1005             Result << "</Unavailable>";
1006           }
1007         }
1008         continue;
1009       }
1010
1011       // 'availability' attribute.
1012       Result << "<Availability";
1013       StringRef Distribution;
1014       if (AA->getPlatform()) {
1015         Distribution = AvailabilityAttr::getPrettyPlatformName(
1016                                         AA->getPlatform()->getName());
1017         if (Distribution.empty())
1018           Distribution = AA->getPlatform()->getName();
1019       }
1020       Result << " distribution=\"" << Distribution << "\">";
1021       VersionTuple IntroducedInVersion = AA->getIntroduced();
1022       if (!IntroducedInVersion.empty()) {
1023         Result << "<IntroducedInVersion>"
1024                << IntroducedInVersion.getAsString()
1025                << "</IntroducedInVersion>";
1026       }
1027       VersionTuple DeprecatedInVersion = AA->getDeprecated();
1028       if (!DeprecatedInVersion.empty()) {
1029         Result << "<DeprecatedInVersion>"
1030                << DeprecatedInVersion.getAsString()
1031                << "</DeprecatedInVersion>";
1032       }
1033       VersionTuple RemovedAfterVersion = AA->getObsoleted();
1034       if (!RemovedAfterVersion.empty()) {
1035         Result << "<RemovedAfterVersion>"
1036                << RemovedAfterVersion.getAsString()
1037                << "</RemovedAfterVersion>";
1038       }
1039       StringRef DeprecationSummary = AA->getMessage();
1040       if (!DeprecationSummary.empty()) {
1041         Result << "<DeprecationSummary>";
1042         appendToResultWithXMLEscaping(DeprecationSummary);
1043         Result << "</DeprecationSummary>";
1044       }
1045       if (AA->getUnavailable())
1046         Result << "<Unavailable/>";
1047       Result << "</Availability>";
1048     }
1049   }
1050
1051   {
1052     bool StartTagEmitted = false;
1053     for (unsigned i = 0, e = Parts.MiscBlocks.size(); i != e; ++i) {
1054       const Comment *C = Parts.MiscBlocks[i];
1055       if (FirstParagraphIsBrief && C == Parts.FirstParagraph)
1056         continue;
1057       if (!StartTagEmitted) {
1058         Result << "<Discussion>";
1059         StartTagEmitted = true;
1060       }
1061       visit(C);
1062     }
1063     if (StartTagEmitted)
1064       Result << "</Discussion>";
1065   }
1066
1067   Result << RootEndTag;
1068 }
1069
1070 void CommentASTToXMLConverter::appendToResultWithXMLEscaping(StringRef S) {
1071   for (StringRef::iterator I = S.begin(), E = S.end(); I != E; ++I) {
1072     const char C = *I;
1073     switch (C) {
1074     case '&':
1075       Result << "&amp;";
1076       break;
1077     case '<':
1078       Result << "&lt;";
1079       break;
1080     case '>':
1081       Result << "&gt;";
1082       break;
1083     case '"':
1084       Result << "&quot;";
1085       break;
1086     case '\'':
1087       Result << "&apos;";
1088       break;
1089     default:
1090       Result << C;
1091       break;
1092     }
1093   }
1094 }
1095
1096 void CommentASTToXMLConverter::appendToResultWithCDATAEscaping(StringRef S) {
1097   if (S.empty())
1098     return;
1099
1100   Result << "<![CDATA[";
1101   while (!S.empty()) {
1102     size_t Pos = S.find("]]>");
1103     if (Pos == 0) {
1104       Result << "]]]]><![CDATA[>";
1105       S = S.drop_front(3);
1106       continue;
1107     }
1108     if (Pos == StringRef::npos)
1109       Pos = S.size();
1110
1111     Result << S.substr(0, Pos);
1112
1113     S = S.drop_front(Pos);
1114   }
1115   Result << "]]>";
1116 }
1117
1118 CommentToXMLConverter::CommentToXMLConverter() {}
1119 CommentToXMLConverter::~CommentToXMLConverter() {}
1120
1121 void CommentToXMLConverter::convertCommentToHTML(const FullComment *FC,
1122                                                  SmallVectorImpl<char> &HTML,
1123                                                  const ASTContext &Context) {
1124   CommentASTToHTMLConverter Converter(FC, HTML,
1125                                       Context.getCommentCommandTraits());
1126   Converter.visit(FC);
1127 }
1128
1129 void CommentToXMLConverter::convertHTMLTagNodeToText(
1130     const comments::HTMLTagComment *HTC, SmallVectorImpl<char> &Text,
1131     const ASTContext &Context) {
1132   CommentASTToHTMLConverter Converter(nullptr, Text,
1133                                       Context.getCommentCommandTraits());
1134   Converter.visit(HTC);
1135 }
1136
1137 void CommentToXMLConverter::convertCommentToXML(const FullComment *FC,
1138                                                 SmallVectorImpl<char> &XML,
1139                                                 const ASTContext &Context) {
1140   CommentASTToXMLConverter Converter(FC, XML, Context.getCommentCommandTraits(),
1141                                      Context.getSourceManager());
1142   Converter.visit(FC);
1143 }