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
22namespace clang {
23class SourceManager;
24
25namespace comments {
26class CommandTraits;
27
28/// Doxygen comment parser.
29class 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
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
60  void consumeToken() {
61    if (MoreLATokens.empty())
62      L.lex(Tok);
63    else
64      Tok = MoreLATokens.pop_back_val();
65  }
66
67  void putBack(const Token &OldTok) {
68    MoreLATokens.push_back(Tok);
69    Tok = OldTok;
70  }
71
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
82  bool isTokBlockCommand() {
83    return (Tok.is(tok::backslash_command) || Tok.is(tok::at_command)) &&
84           Traits.getCommandInfo(Tok.getCommandID())->IsBlockCommand;
85  }
86
87public:
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