1//===- CXComment.cpp - libclang APIs for manipulating CXComments ----------===//
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// This file defines all libclang APIs related to walking comment AST.
10//
11//===----------------------------------------------------------------------===//
12
13#include "CXComment.h"
14#include "CXCursor.h"
15#include "CXString.h"
16#include "clang-c/Documentation.h"
17#include "clang-c/Index.h"
18#include "clang/AST/Decl.h"
19#include "clang/Index/CommentToXML.h"
20#include "llvm/ADT/StringExtras.h"
21#include "llvm/Support/ErrorHandling.h"
22#include <climits>
23
24using namespace clang;
25using namespace clang::comments;
26using namespace clang::cxcomment;
27
28CXComment clang_Cursor_getParsedComment(CXCursor C) {
29 using namespace clang::cxcursor;
30
31 if (!clang_isDeclaration(C.kind))
32 return createCXComment(C: nullptr, TU: nullptr);
33
34 const Decl *D = getCursorDecl(Cursor: C);
35 const ASTContext &Context = getCursorContext(Cursor: C);
36 const FullComment *FC = Context.getCommentForDecl(D, /*PP=*/nullptr);
37
38 return createCXComment(C: FC, TU: getCursorTU(Cursor: C));
39}
40
41enum CXCommentKind clang_Comment_getKind(CXComment CXC) {
42 const Comment *C = getASTNode(CXC);
43 if (!C)
44 return CXComment_Null;
45
46 switch (C->getCommentKind()) {
47 case CommentKind::None:
48 return CXComment_Null;
49
50 case CommentKind::TextComment:
51 return CXComment_Text;
52
53 case CommentKind::InlineCommandComment:
54 return CXComment_InlineCommand;
55
56 case CommentKind::HTMLStartTagComment:
57 return CXComment_HTMLStartTag;
58
59 case CommentKind::HTMLEndTagComment:
60 return CXComment_HTMLEndTag;
61
62 case CommentKind::ParagraphComment:
63 return CXComment_Paragraph;
64
65 case CommentKind::BlockCommandComment:
66 return CXComment_BlockCommand;
67
68 case CommentKind::ParamCommandComment:
69 return CXComment_ParamCommand;
70
71 case CommentKind::TParamCommandComment:
72 return CXComment_TParamCommand;
73
74 case CommentKind::VerbatimBlockComment:
75 return CXComment_VerbatimBlockCommand;
76
77 case CommentKind::VerbatimBlockLineComment:
78 return CXComment_VerbatimBlockLine;
79
80 case CommentKind::VerbatimLineComment:
81 return CXComment_VerbatimLine;
82
83 case CommentKind::FullComment:
84 return CXComment_FullComment;
85 }
86 llvm_unreachable("unknown CommentKind");
87}
88
89unsigned clang_Comment_getNumChildren(CXComment CXC) {
90 const Comment *C = getASTNode(CXC);
91 if (!C)
92 return 0;
93
94 return C->child_count();
95}
96
97CXComment clang_Comment_getChild(CXComment CXC, unsigned ChildIdx) {
98 const Comment *C = getASTNode(CXC);
99 if (!C || ChildIdx >= C->child_count())
100 return createCXComment(C: nullptr, TU: nullptr);
101
102 return createCXComment(C: *(C->child_begin() + ChildIdx), TU: CXC.TranslationUnit);
103}
104
105unsigned clang_Comment_isWhitespace(CXComment CXC) {
106 const Comment *C = getASTNode(CXC);
107 if (!C)
108 return false;
109
110 if (const TextComment *TC = dyn_cast<TextComment>(Val: C))
111 return TC->isWhitespace();
112
113 if (const ParagraphComment *PC = dyn_cast<ParagraphComment>(Val: C))
114 return PC->isWhitespace();
115
116 return false;
117}
118
119unsigned clang_InlineContentComment_hasTrailingNewline(CXComment CXC) {
120 const InlineContentComment *ICC = getASTNodeAs<InlineContentComment>(CXC);
121 if (!ICC)
122 return false;
123
124 return ICC->hasTrailingNewline();
125}
126
127CXString clang_TextComment_getText(CXComment CXC) {
128 const TextComment *TC = getASTNodeAs<TextComment>(CXC);
129 if (!TC)
130 return cxstring::createNull();
131
132 return cxstring::createRef(String: TC->getText());
133}
134
135CXString clang_InlineCommandComment_getCommandName(CXComment CXC) {
136 const InlineCommandComment *ICC = getASTNodeAs<InlineCommandComment>(CXC);
137 if (!ICC)
138 return cxstring::createNull();
139
140 const CommandTraits &Traits = getCommandTraits(CXC);
141 return cxstring::createRef(String: ICC->getCommandName(Traits));
142}
143
144enum CXCommentInlineCommandRenderKind
145clang_InlineCommandComment_getRenderKind(CXComment CXC) {
146 const InlineCommandComment *ICC = getASTNodeAs<InlineCommandComment>(CXC);
147 if (!ICC)
148 return CXCommentInlineCommandRenderKind_Normal;
149
150 switch (ICC->getRenderKind()) {
151 case InlineCommandRenderKind::Normal:
152 return CXCommentInlineCommandRenderKind_Normal;
153
154 case InlineCommandRenderKind::Bold:
155 return CXCommentInlineCommandRenderKind_Bold;
156
157 case InlineCommandRenderKind::Monospaced:
158 return CXCommentInlineCommandRenderKind_Monospaced;
159
160 case InlineCommandRenderKind::Emphasized:
161 return CXCommentInlineCommandRenderKind_Emphasized;
162
163 case InlineCommandRenderKind::Anchor:
164 return CXCommentInlineCommandRenderKind_Anchor;
165 }
166 llvm_unreachable("unknown InlineCommandComment::RenderKind");
167}
168
169unsigned clang_InlineCommandComment_getNumArgs(CXComment CXC) {
170 const InlineCommandComment *ICC = getASTNodeAs<InlineCommandComment>(CXC);
171 if (!ICC)
172 return 0;
173
174 return ICC->getNumArgs();
175}
176
177CXString clang_InlineCommandComment_getArgText(CXComment CXC,
178 unsigned ArgIdx) {
179 const InlineCommandComment *ICC = getASTNodeAs<InlineCommandComment>(CXC);
180 if (!ICC || ArgIdx >= ICC->getNumArgs())
181 return cxstring::createNull();
182
183 return cxstring::createRef(String: ICC->getArgText(Idx: ArgIdx));
184}
185
186CXString clang_HTMLTagComment_getTagName(CXComment CXC) {
187 const HTMLTagComment *HTC = getASTNodeAs<HTMLTagComment>(CXC);
188 if (!HTC)
189 return cxstring::createNull();
190
191 return cxstring::createRef(String: HTC->getTagName());
192}
193
194unsigned clang_HTMLStartTagComment_isSelfClosing(CXComment CXC) {
195 const HTMLStartTagComment *HST = getASTNodeAs<HTMLStartTagComment>(CXC);
196 if (!HST)
197 return false;
198
199 return HST->isSelfClosing();
200}
201
202unsigned clang_HTMLStartTag_getNumAttrs(CXComment CXC) {
203 const HTMLStartTagComment *HST = getASTNodeAs<HTMLStartTagComment>(CXC);
204 if (!HST)
205 return 0;
206
207 return HST->getNumAttrs();
208}
209
210CXString clang_HTMLStartTag_getAttrName(CXComment CXC, unsigned AttrIdx) {
211 const HTMLStartTagComment *HST = getASTNodeAs<HTMLStartTagComment>(CXC);
212 if (!HST || AttrIdx >= HST->getNumAttrs())
213 return cxstring::createNull();
214
215 return cxstring::createRef(String: HST->getAttr(Idx: AttrIdx).Name);
216}
217
218CXString clang_HTMLStartTag_getAttrValue(CXComment CXC, unsigned AttrIdx) {
219 const HTMLStartTagComment *HST = getASTNodeAs<HTMLStartTagComment>(CXC);
220 if (!HST || AttrIdx >= HST->getNumAttrs())
221 return cxstring::createNull();
222
223 return cxstring::createRef(String: HST->getAttr(Idx: AttrIdx).Value);
224}
225
226CXString clang_BlockCommandComment_getCommandName(CXComment CXC) {
227 const BlockCommandComment *BCC = getASTNodeAs<BlockCommandComment>(CXC);
228 if (!BCC)
229 return cxstring::createNull();
230
231 const CommandTraits &Traits = getCommandTraits(CXC);
232 return cxstring::createRef(String: BCC->getCommandName(Traits));
233}
234
235unsigned clang_BlockCommandComment_getNumArgs(CXComment CXC) {
236 const BlockCommandComment *BCC = getASTNodeAs<BlockCommandComment>(CXC);
237 if (!BCC)
238 return 0;
239
240 return BCC->getNumArgs();
241}
242
243CXString clang_BlockCommandComment_getArgText(CXComment CXC,
244 unsigned ArgIdx) {
245 const BlockCommandComment *BCC = getASTNodeAs<BlockCommandComment>(CXC);
246 if (!BCC || ArgIdx >= BCC->getNumArgs())
247 return cxstring::createNull();
248
249 return cxstring::createRef(String: BCC->getArgText(Idx: ArgIdx));
250}
251
252CXComment clang_BlockCommandComment_getParagraph(CXComment CXC) {
253 const BlockCommandComment *BCC = getASTNodeAs<BlockCommandComment>(CXC);
254 if (!BCC)
255 return createCXComment(C: nullptr, TU: nullptr);
256
257 return createCXComment(C: BCC->getParagraph(), TU: CXC.TranslationUnit);
258}
259
260CXString clang_ParamCommandComment_getParamName(CXComment CXC) {
261 const ParamCommandComment *PCC = getASTNodeAs<ParamCommandComment>(CXC);
262 if (!PCC || !PCC->hasParamName())
263 return cxstring::createNull();
264
265 return cxstring::createRef(String: PCC->getParamNameAsWritten());
266}
267
268unsigned clang_ParamCommandComment_isParamIndexValid(CXComment CXC) {
269 const ParamCommandComment *PCC = getASTNodeAs<ParamCommandComment>(CXC);
270 if (!PCC)
271 return false;
272
273 return PCC->isParamIndexValid();
274}
275
276unsigned clang_ParamCommandComment_getParamIndex(CXComment CXC) {
277 const ParamCommandComment *PCC = getASTNodeAs<ParamCommandComment>(CXC);
278 if (!PCC || !PCC->isParamIndexValid() || PCC->isVarArgParam())
279 return ParamCommandComment::InvalidParamIndex;
280
281 return PCC->getParamIndex();
282}
283
284unsigned clang_ParamCommandComment_isDirectionExplicit(CXComment CXC) {
285 const ParamCommandComment *PCC = getASTNodeAs<ParamCommandComment>(CXC);
286 if (!PCC)
287 return false;
288
289 return PCC->isDirectionExplicit();
290}
291
292enum CXCommentParamPassDirection clang_ParamCommandComment_getDirection(
293 CXComment CXC) {
294 const ParamCommandComment *PCC = getASTNodeAs<ParamCommandComment>(CXC);
295 if (!PCC)
296 return CXCommentParamPassDirection_In;
297
298 switch (PCC->getDirection()) {
299 case ParamCommandPassDirection::In:
300 return CXCommentParamPassDirection_In;
301
302 case ParamCommandPassDirection::Out:
303 return CXCommentParamPassDirection_Out;
304
305 case ParamCommandPassDirection::InOut:
306 return CXCommentParamPassDirection_InOut;
307 }
308 llvm_unreachable("unknown ParamCommandComment::PassDirection");
309}
310
311CXString clang_TParamCommandComment_getParamName(CXComment CXC) {
312 const TParamCommandComment *TPCC = getASTNodeAs<TParamCommandComment>(CXC);
313 if (!TPCC || !TPCC->hasParamName())
314 return cxstring::createNull();
315
316 return cxstring::createRef(String: TPCC->getParamNameAsWritten());
317}
318
319unsigned clang_TParamCommandComment_isParamPositionValid(CXComment CXC) {
320 const TParamCommandComment *TPCC = getASTNodeAs<TParamCommandComment>(CXC);
321 if (!TPCC)
322 return false;
323
324 return TPCC->isPositionValid();
325}
326
327unsigned clang_TParamCommandComment_getDepth(CXComment CXC) {
328 const TParamCommandComment *TPCC = getASTNodeAs<TParamCommandComment>(CXC);
329 if (!TPCC || !TPCC->isPositionValid())
330 return 0;
331
332 return TPCC->getDepth();
333}
334
335unsigned clang_TParamCommandComment_getIndex(CXComment CXC, unsigned Depth) {
336 const TParamCommandComment *TPCC = getASTNodeAs<TParamCommandComment>(CXC);
337 if (!TPCC || !TPCC->isPositionValid() || Depth >= TPCC->getDepth())
338 return 0;
339
340 return TPCC->getIndex(Depth);
341}
342
343CXString clang_VerbatimBlockLineComment_getText(CXComment CXC) {
344 const VerbatimBlockLineComment *VBL =
345 getASTNodeAs<VerbatimBlockLineComment>(CXC);
346 if (!VBL)
347 return cxstring::createNull();
348
349 return cxstring::createRef(String: VBL->getText());
350}
351
352CXString clang_VerbatimLineComment_getText(CXComment CXC) {
353 const VerbatimLineComment *VLC = getASTNodeAs<VerbatimLineComment>(CXC);
354 if (!VLC)
355 return cxstring::createNull();
356
357 return cxstring::createRef(String: VLC->getText());
358}
359
360//===----------------------------------------------------------------------===//
361// Converting comments to XML.
362//===----------------------------------------------------------------------===//
363
364CXString clang_HTMLTagComment_getAsString(CXComment CXC) {
365 const HTMLTagComment *HTC = getASTNodeAs<HTMLTagComment>(CXC);
366 if (!HTC)
367 return cxstring::createNull();
368
369 CXTranslationUnit TU = CXC.TranslationUnit;
370 if (!TU->CommentToXML)
371 TU->CommentToXML = new clang::index::CommentToXMLConverter();
372
373 SmallString<128> Text;
374 TU->CommentToXML->convertHTMLTagNodeToText(
375 HTC, Text, Context: cxtu::getASTUnit(TU)->getASTContext());
376 return cxstring::createDup(String: Text.str());
377}
378
379CXString clang_FullComment_getAsHTML(CXComment CXC) {
380 const FullComment *FC = getASTNodeAs<FullComment>(CXC);
381 if (!FC)
382 return cxstring::createNull();
383
384 CXTranslationUnit TU = CXC.TranslationUnit;
385 if (!TU->CommentToXML)
386 TU->CommentToXML = new clang::index::CommentToXMLConverter();
387
388 SmallString<1024> HTML;
389 TU->CommentToXML
390 ->convertCommentToHTML(FC, HTML, Context: cxtu::getASTUnit(TU)->getASTContext());
391 return cxstring::createDup(String: HTML.str());
392}
393
394CXString clang_FullComment_getAsXML(CXComment CXC) {
395 const FullComment *FC = getASTNodeAs<FullComment>(CXC);
396 if (!FC)
397 return cxstring::createNull();
398
399 CXTranslationUnit TU = CXC.TranslationUnit;
400 if (!TU->CommentToXML)
401 TU->CommentToXML = new clang::index::CommentToXMLConverter();
402
403 SmallString<1024> XML;
404 TU->CommentToXML
405 ->convertCommentToXML(FC, XML, Context: cxtu::getASTUnit(TU)->getASTContext());
406 return cxstring::createDup(String: XML.str());
407}
408
409