clang  14.0.0git
CommentParser.h
Go to the documentation of this file.
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 
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)) &&
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 
clang::comments::TextTokenRetokenizer
Re-lexes a sequence of tok::text tokens.
Definition: CommentParser.cpp:30
clang::comments::Parser::parseHTMLStartTag
HTMLStartTagComment * parseHTMLStartTag()
Definition: CommentParser.cpp:438
clang::comments::Parser::parseVerbatimBlock
VerbatimBlockComment * parseVerbatimBlock()
Definition: CommentParser.cpp:659
clang::DiagnosticBuilder
A little helper class used to produce diagnostics.
Definition: Diagnostic.h:1264
clang::comments::Sema
Definition: CommentSema.h:32
Diag
static DiagnosticBuilder Diag(DiagnosticsEngine *Diags, const LangOptions &Features, FullSourceLoc TokLoc, const char *TokBegin, const char *TokRangeBegin, const char *TokRangeEnd, unsigned DiagID)
Produce a diagnostic highlighting some portion of a literal.
Definition: LiteralSupport.cpp:78
llvm::SmallVector
Definition: LLVM.h:38
clang::SourceLocation
Encodes a location in the source.
Definition: SourceLocation.h:88
clang::comments::Parser::parseParamCommandArgs
void parseParamCommandArgs(ParamCommandComment *PC, TextTokenRetokenizer &Retokenizer)
Parse arguments for \param command.
Definition: CommentParser.cpp:264
clang::DiagnosticsEngine
Concrete class used by the front-end to report problems and issues.
Definition: Diagnostic.h:191
clang::Token
Token - This structure provides full information about a lexed token.
Definition: Token.h:34
clang::comments::CommandInfo::IsBlockCommand
unsigned IsBlockCommand
True if this command is a block command (of any kind).
Definition: CommentCommandTraits.h:56
clang::SourceManager
This class handles loading and caching of source files into memory.
Definition: SourceManager.h:626
clang::comments::CommandTraits::getCommandInfo
const CommandInfo * getCommandInfo(StringRef Name) const
Definition: CommentCommandTraits.h:145
clang::comments::Parser::parseTParamCommandArgs
void parseTParamCommandArgs(TParamCommandComment *TPC, TextTokenRetokenizer &Retokenizer)
Parse arguments for \tparam command.
Definition: CommentParser.cpp:282
clang::comments::Parser::TextTokenRetokenizer
friend class TextTokenRetokenizer
Definition: CommentParser.h:33
clang::comments::Token::getCommandID
unsigned getCommandID() const LLVM_READONLY
Definition: CommentLexer.h:120
Diagnostic.h
CommentSema.h
clang::comments::Parser::parseFullComment
FullComment * parseFullComment()
Definition: CommentParser.cpp:763
clang::comments::Token
Comment token.
Definition: CommentLexer.h:55
clang::comments::tok::at_command
@ at_command
Definition: CommentLexer.h:38
clang::comments::Parser::parseInlineCommand
InlineCommandComment * parseInlineCommand()
Definition: CommentParser.cpp:402
clang::comments::Parser::parseBlockContent
BlockContentComment * parseBlockContent()
Definition: CommentParser.cpp:732
clang::comments::Parser::parseBlockCommandArgs
void parseBlockCommandArgs(BlockCommandComment *BC, TextTokenRetokenizer &Retokenizer, unsigned NumArgs)
Definition: CommentParser.cpp:292
clang::comments::Parser::parseParagraphOrBlockCommand
BlockContentComment * parseParagraphOrBlockCommand()
Definition: CommentParser.cpp:558
clang::comments::Token::is
bool is(tok::TokenKind K) const LLVM_READONLY
Definition: CommentLexer.h:92
clang
Definition: CalledOnceCheck.h:17
Comment.h
clang::comments::Parser
Doxygen comment parser.
Definition: CommentParser.h:29
clang::comments::Lexer::lex
void lex(Token &T)
Definition: CommentLexer.cpp:749
clang::comments::Parser::parseHTMLEndTag
HTMLEndTagComment * parseHTMLEndTag()
Definition: CommentParser.cpp:543
clang::comments::Parser::parseVerbatimLine
VerbatimLineComment * parseVerbatimLine()
Definition: CommentParser.cpp:706
clang::comments::CommandTraits
This class provides information about commands that can be used in comments.
Definition: CommentCommandTraits.h:127
clang::comments::Parser::parseBlockCommand
BlockCommandComment * parseBlockCommand()
Definition: CommentParser.cpp:310
clang::comments::tok::backslash_command
@ backslash_command
Definition: CommentLexer.h:37
CommentLexer.h
clang::comments::Lexer
Comment lexer.
Definition: CommentLexer.h:220
clang::DiagnosticsEngine::Report
DiagnosticBuilder Report(SourceLocation Loc, unsigned DiagID)
Issue the message to the client.
Definition: Diagnostic.h:1523