1 //===--- CommentParser.h - Doxygen comment parser ---------------*- C++ -*-===//
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 the Doxygen comment parser.
10 //
11 //===----------------------------------------------------------------------===//
12 
13 #ifndef LLVM_CLANG_AST_COMMENTPARSER_H
14 #define LLVM_CLANG_AST_COMMENTPARSER_H
15 
16 #include "clang/AST/Comment.h"
17 #include "clang/AST/CommentLexer.h"
18 #include "clang/AST/CommentSema.h"
19 #include "clang/Basic/Diagnostic.h"
20 #include "llvm/Support/Allocator.h"
21 
22 namespace clang {
23 class SourceManager;
24 
25 namespace comments {
26 class CommandTraits;
27 
28 /// Doxygen comment parser.
29 class Parser {
30   Parser(const Parser &) = delete;
31   void operator=(const Parser &) = delete;
32 
33   friend class TextTokenRetokenizer;
34 
35   Lexer &L;
36 
37   Sema &S;
38 
39   /// Allocator for anything that goes into AST nodes.
40   llvm::BumpPtrAllocator &Allocator;
41 
42   /// Source manager for the comment being parsed.
43   const SourceManager &SourceMgr;
44 
45   DiagnosticsEngine &Diags;
46 
Diag(SourceLocation Loc,unsigned DiagID)47   DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) {
48     return Diags.Report(Loc, DiagID);
49   }
50 
51   const CommandTraits &Traits;
52 
53   /// Current lookahead token.  We can safely assume that all tokens are from
54   /// a single source file.
55   Token Tok;
56 
57   /// A stack of additional lookahead tokens.
58   SmallVector<Token, 8> MoreLATokens;
59 
consumeToken()60   void consumeToken() {
61     if (MoreLATokens.empty())
62       L.lex(Tok);
63     else
64       Tok = MoreLATokens.pop_back_val();
65   }
66 
putBack(const Token & OldTok)67   void putBack(const Token &OldTok) {
68     MoreLATokens.push_back(Tok);
69     Tok = OldTok;
70   }
71 
putBack(ArrayRef<Token> Toks)72   void putBack(ArrayRef<Token> Toks) {
73     if (Toks.empty())
74       return;
75 
76     MoreLATokens.push_back(Tok);
77     MoreLATokens.append(Toks.rbegin(), std::prev(Toks.rend()));
78 
79     Tok = Toks[0];
80   }
81 
isTokBlockCommand()82   bool isTokBlockCommand() {
83     return (Tok.is(tok::backslash_command) || Tok.is(tok::at_command)) &&
84            Traits.getCommandInfo(Tok.getCommandID())->IsBlockCommand;
85   }
86 
87 public:
88   Parser(Lexer &L, Sema &S, llvm::BumpPtrAllocator &Allocator,
89          const SourceManager &SourceMgr, DiagnosticsEngine &Diags,
90          const CommandTraits &Traits);
91 
92   /// Parse arguments for \\param command.
93   void parseParamCommandArgs(ParamCommandComment *PC,
94                              TextTokenRetokenizer &Retokenizer);
95 
96   /// Parse arguments for \\tparam command.
97   void parseTParamCommandArgs(TParamCommandComment *TPC,
98                               TextTokenRetokenizer &Retokenizer);
99 
100   void parseBlockCommandArgs(BlockCommandComment *BC,
101                              TextTokenRetokenizer &Retokenizer,
102                              unsigned NumArgs);
103 
104   BlockCommandComment *parseBlockCommand();
105   InlineCommandComment *parseInlineCommand();
106 
107   HTMLStartTagComment *parseHTMLStartTag();
108   HTMLEndTagComment *parseHTMLEndTag();
109 
110   BlockContentComment *parseParagraphOrBlockCommand();
111 
112   VerbatimBlockComment *parseVerbatimBlock();
113   VerbatimLineComment *parseVerbatimLine();
114   BlockContentComment *parseBlockContent();
115   FullComment *parseFullComment();
116 };
117 
118 } // end namespace comments
119 } // end namespace clang
120 
121 #endif
122 
123