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