1 //===--- NamespaceCommentCheck.cpp - clang-tidy ---------------------------===// 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 #include "NamespaceCommentCheck.h" 10 #include "../utils/LexerUtils.h" 11 #include "clang/AST/ASTContext.h" 12 #include "clang/ASTMatchers/ASTMatchers.h" 13 #include "clang/Basic/SourceLocation.h" 14 #include "clang/Basic/TokenKinds.h" 15 #include "clang/Lex/Lexer.h" 16 #include "llvm/ADT/StringExtras.h" 17 #include <optional> 18 19 using namespace clang::ast_matchers; 20 21 namespace clang::tidy::readability { 22 23 NamespaceCommentCheck::NamespaceCommentCheck(StringRef Name, 24 ClangTidyContext *Context) 25 : ClangTidyCheck(Name, Context), 26 NamespaceCommentPattern( 27 "^/[/*] *(end (of )?)? *(anonymous|unnamed)? *" 28 "namespace( +(((inline )|([a-zA-Z0-9_:]))+))?\\.? *(\\*/)?$", 29 llvm::Regex::IgnoreCase), 30 ShortNamespaceLines(Options.get("ShortNamespaceLines", 1u)), 31 SpacesBeforeComments(Options.get("SpacesBeforeComments", 1u)) {} 32 33 void NamespaceCommentCheck::storeOptions(ClangTidyOptions::OptionMap &Opts) { 34 Options.store(Opts, "ShortNamespaceLines", ShortNamespaceLines); 35 Options.store(Opts, "SpacesBeforeComments", SpacesBeforeComments); 36 } 37 38 void NamespaceCommentCheck::registerMatchers(MatchFinder *Finder) { 39 Finder->addMatcher(namespaceDecl().bind("namespace"), this); 40 } 41 42 static bool locationsInSameFile(const SourceManager &Sources, 43 SourceLocation Loc1, SourceLocation Loc2) { 44 return Loc1.isFileID() && Loc2.isFileID() && 45 Sources.getFileID(Loc1) == Sources.getFileID(Loc2); 46 } 47 48 static std::optional<std::string> 49 getNamespaceNameAsWritten(SourceLocation &Loc, const SourceManager &Sources, 50 const LangOptions &LangOpts) { 51 // Loc should be at the begin of the namespace decl (usually, `namespace` 52 // token). We skip the first token right away, but in case of `inline 53 // namespace` or `namespace a::inline b` we can see both `inline` and 54 // `namespace` keywords, which we just ignore. Nested parens/squares before 55 // the opening brace can result from attributes. 56 std::string Result; 57 int Nesting = 0; 58 while (std::optional<Token> T = utils::lexer::findNextTokenSkippingComments( 59 Loc, Sources, LangOpts)) { 60 Loc = T->getLocation(); 61 if (T->is(tok::l_brace)) 62 break; 63 64 if (T->isOneOf(tok::l_square, tok::l_paren)) { 65 ++Nesting; 66 } else if (T->isOneOf(tok::r_square, tok::r_paren)) { 67 --Nesting; 68 } else if (Nesting == 0) { 69 if (T->is(tok::raw_identifier)) { 70 StringRef ID = T->getRawIdentifier(); 71 if (ID != "namespace") 72 Result.append(std::string(ID)); 73 if (ID == "inline") 74 Result.append(" "); 75 } else if (T->is(tok::coloncolon)) { 76 Result.append("::"); 77 } else { // Any other kind of token is unexpected here. 78 return std::nullopt; 79 } 80 } 81 } 82 return Result; 83 } 84 85 void NamespaceCommentCheck::check(const MatchFinder::MatchResult &Result) { 86 const auto *ND = Result.Nodes.getNodeAs<NamespaceDecl>("namespace"); 87 const SourceManager &Sources = *Result.SourceManager; 88 89 // Ignore namespaces inside macros and namespaces split across files. 90 if (ND->getBeginLoc().isMacroID() || 91 !locationsInSameFile(Sources, ND->getBeginLoc(), ND->getRBraceLoc())) 92 return; 93 94 // Don't require closing comments for namespaces spanning less than certain 95 // number of lines. 96 unsigned StartLine = Sources.getSpellingLineNumber(ND->getBeginLoc()); 97 unsigned EndLine = Sources.getSpellingLineNumber(ND->getRBraceLoc()); 98 if (EndLine - StartLine + 1 <= ShortNamespaceLines) 99 return; 100 101 // Find next token after the namespace closing brace. 102 SourceLocation AfterRBrace = Lexer::getLocForEndOfToken( 103 ND->getRBraceLoc(), /*Offset=*/0, Sources, getLangOpts()); 104 SourceLocation Loc = AfterRBrace; 105 SourceLocation LBraceLoc = ND->getBeginLoc(); 106 107 // Currently for nested namespace (n1::n2::...) the AST matcher will match foo 108 // then bar instead of a single match. So if we got a nested namespace we have 109 // to skip the next ones. 110 for (const auto &EndOfNameLocation : Ends) { 111 if (Sources.isBeforeInTranslationUnit(ND->getLocation(), EndOfNameLocation)) 112 return; 113 } 114 115 std::optional<std::string> NamespaceNameAsWritten = 116 getNamespaceNameAsWritten(LBraceLoc, Sources, getLangOpts()); 117 if (!NamespaceNameAsWritten) 118 return; 119 120 if (NamespaceNameAsWritten->empty() != ND->isAnonymousNamespace()) { 121 // Apparently, we didn't find the correct namespace name. Give up. 122 return; 123 } 124 125 Ends.push_back(LBraceLoc); 126 127 Token Tok; 128 // Skip whitespace until we find the next token. 129 while (Lexer::getRawToken(Loc, Tok, Sources, getLangOpts()) || 130 Tok.is(tok::semi)) { 131 Loc = Loc.getLocWithOffset(1); 132 } 133 134 if (!locationsInSameFile(Sources, ND->getRBraceLoc(), Loc)) 135 return; 136 137 bool NextTokenIsOnSameLine = Sources.getSpellingLineNumber(Loc) == EndLine; 138 // If we insert a line comment before the token in the same line, we need 139 // to insert a line break. 140 bool NeedLineBreak = NextTokenIsOnSameLine && Tok.isNot(tok::eof); 141 142 SourceRange OldCommentRange(AfterRBrace, AfterRBrace); 143 std::string Message = "%0 not terminated with a closing comment"; 144 145 // Try to find existing namespace closing comment on the same line. 146 if (Tok.is(tok::comment) && NextTokenIsOnSameLine) { 147 StringRef Comment(Sources.getCharacterData(Loc), Tok.getLength()); 148 SmallVector<StringRef, 7> Groups; 149 if (NamespaceCommentPattern.match(Comment, &Groups)) { 150 StringRef NamespaceNameInComment = Groups.size() > 5 ? Groups[5] : ""; 151 StringRef Anonymous = Groups.size() > 3 ? Groups[3] : ""; 152 153 if ((ND->isAnonymousNamespace() && NamespaceNameInComment.empty()) || 154 (*NamespaceNameAsWritten == NamespaceNameInComment && 155 Anonymous.empty())) { 156 // Check if the namespace in the comment is the same. 157 // FIXME: Maybe we need a strict mode, where we always fix namespace 158 // comments with different format. 159 return; 160 } 161 162 // Otherwise we need to fix the comment. 163 NeedLineBreak = Comment.startswith("/*"); 164 OldCommentRange = 165 SourceRange(AfterRBrace, Loc.getLocWithOffset(Tok.getLength())); 166 Message = 167 (llvm::Twine( 168 "%0 ends with a comment that refers to a wrong namespace '") + 169 NamespaceNameInComment + "'") 170 .str(); 171 } else if (Comment.startswith("//")) { 172 // Assume that this is an unrecognized form of a namespace closing line 173 // comment. Replace it. 174 NeedLineBreak = false; 175 OldCommentRange = 176 SourceRange(AfterRBrace, Loc.getLocWithOffset(Tok.getLength())); 177 Message = "%0 ends with an unrecognized comment"; 178 } 179 // If it's a block comment, just move it to the next line, as it can be 180 // multi-line or there may be other tokens behind it. 181 } 182 183 std::string NamespaceNameForDiag = 184 ND->isAnonymousNamespace() ? "anonymous namespace" 185 : ("namespace '" + *NamespaceNameAsWritten + "'"); 186 187 std::string Fix(SpacesBeforeComments, ' '); 188 Fix.append("// namespace"); 189 if (!ND->isAnonymousNamespace()) 190 Fix.append(" ").append(*NamespaceNameAsWritten); 191 if (NeedLineBreak) 192 Fix.append("\n"); 193 194 // Place diagnostic at an old comment, or closing brace if we did not have it. 195 SourceLocation DiagLoc = 196 OldCommentRange.getBegin() != OldCommentRange.getEnd() 197 ? OldCommentRange.getBegin() 198 : ND->getRBraceLoc(); 199 200 diag(DiagLoc, Message) << NamespaceNameForDiag 201 << FixItHint::CreateReplacement( 202 CharSourceRange::getCharRange(OldCommentRange), 203 Fix); 204 diag(ND->getLocation(), "%0 starts here", DiagnosticIDs::Note) 205 << NamespaceNameForDiag; 206 } 207 208 } // namespace clang::tidy::readability 209