clang/AST/CommentParser.h

0001 //===--- CommentParser.h - Doxygen comment parser ---------------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008 //
0009 //  This file defines the Doxygen comment parser.
0010 //
0011 //===----------------------------------------------------------------------===//
0012
0013 #ifndef LLVM_CLANG_AST_COMMENTPARSER_H
0014 #define LLVM_CLANG_AST_COMMENTPARSER_H
0015
0016 #include "clang/AST/Comment.h"
0017 #include "clang/AST/CommentLexer.h"
0018 #include "clang/AST/CommentSema.h"
0019 #include "clang/Basic/Diagnostic.h"
0020 #include "llvm/Support/Allocator.h"
0021
0022 namespace clang {
0023 class SourceManager;
0024
0025 namespace comments {
0026 class CommandTraits;
0027
0028 /// Doxygen comment parser.
0029 class Parser {
0030   Parser(const Parser &) = delete;
0031   void operator=(const Parser &) = delete;
0032
0033   friend class TextTokenRetokenizer;
0034
0035   Lexer &L;
0036
0037   Sema &S;
0038
0039   /// Allocator for anything that goes into AST nodes.
0040   llvm::BumpPtrAllocator &Allocator;
0041
0042   /// Source manager for the comment being parsed.
0043   const SourceManager &SourceMgr;
0044
0045   DiagnosticsEngine &Diags;
0046
0047   DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) {
0048     return Diags.Report(Loc, DiagID);
0049   }
0050
0051   const CommandTraits &Traits;
0052
0053   /// Current lookahead token.  We can safely assume that all tokens are from
0054   /// a single source file.
0055   Token Tok;
0056
0057   /// A stack of additional lookahead tokens.
0058   SmallVector<Token, 8> MoreLATokens;
0059
0060   void consumeToken() {
0061     if (MoreLATokens.empty())
0062       L.lex(Tok);
0063     else
0064       Tok = MoreLATokens.pop_back_val();
0065   }
0066
0067   void putBack(const Token &OldTok) {
0068     MoreLATokens.push_back(Tok);
0069     Tok = OldTok;
0070   }
0071
0072   void putBack(ArrayRef<Token> Toks) {
0073     if (Toks.empty())
0074       return;
0075
0076     MoreLATokens.push_back(Tok);
0077     MoreLATokens.append(Toks.rbegin(), std::prev(Toks.rend()));
0078
0079     Tok = Toks[0];
0080   }
0081
0082   bool isTokBlockCommand() {
0083     return (Tok.is(tok::backslash_command) || Tok.is(tok::at_command)) &&
0084            Traits.getCommandInfo(Tok.getCommandID())->IsBlockCommand;
0085   }
0086
0087 public:
0088   Parser(Lexer &L, Sema &S, llvm::BumpPtrAllocator &Allocator,
0089          const SourceManager &SourceMgr, DiagnosticsEngine &Diags,
0090          const CommandTraits &Traits);
0091
0092   /// Parse arguments for \\param command.
0093   void parseParamCommandArgs(ParamCommandComment *PC,
0094                              TextTokenRetokenizer &Retokenizer);
0095
0096   /// Parse arguments for \\tparam command.
0097   void parseTParamCommandArgs(TParamCommandComment *TPC,
0098                               TextTokenRetokenizer &Retokenizer);
0099
0100   ArrayRef<Comment::Argument>
0101   parseCommandArgs(TextTokenRetokenizer &Retokenizer, unsigned NumArgs);
0102
0103   /// Parse arguments for \throws command supported args are in form of class
0104   /// or template.
0105   ArrayRef<Comment::Argument>
0106   parseThrowCommandArgs(TextTokenRetokenizer &Retokenizer, unsigned NumArgs);
0107
0108   ArrayRef<Comment::Argument>
0109   parseParCommandArgs(TextTokenRetokenizer &Retokenizer, unsigned NumArgs);
0110
0111   BlockCommandComment *parseBlockCommand();
0112   InlineCommandComment *parseInlineCommand();
0113
0114   HTMLStartTagComment *parseHTMLStartTag();
0115   HTMLEndTagComment *parseHTMLEndTag();
0116
0117   BlockContentComment *parseParagraphOrBlockCommand();
0118
0119   VerbatimBlockComment *parseVerbatimBlock();
0120   VerbatimLineComment *parseVerbatimLine();
0121   BlockContentComment *parseBlockContent();
0122   FullComment *parseFullComment();
0123 };
0124
0125 } // end namespace comments
0126 } // end namespace clang
0127
0128 #endif