clang-tools 19.0.0git
NamespaceCommentCheck.cpp
Go to the documentation of this file.
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
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
19using namespace clang::ast_matchers;
20
22
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
33void NamespaceCommentCheck::storeOptions(ClangTidyOptions::OptionMap &Opts) {
34 Options.store(Opts, "ShortNamespaceLines", ShortNamespaceLines);
35 Options.store(Opts, "SpacesBeforeComments", SpacesBeforeComments);
36}
37
38void NamespaceCommentCheck::registerMatchers(MatchFinder *Finder) {
39 Finder->addMatcher(namespaceDecl().bind("namespace"), this);
40}
41
42static 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
48static std::optional<std::string>
49getNamespaceNameAsWritten(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
85void 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.starts_with("/*");
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.starts_with("//")) {
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
llvm::SmallString< 256U > Name
static cl::opt< bool > Fix("fix", desc(R"( Apply suggested fixes. Without -fix-errors clang-tidy will bail out if any compilation errors were found. )"), cl::init(false), cl::cat(ClangTidyCategory))
const unsigned short Nesting
SourceLocation Loc
void store(ClangTidyOptions::OptionMap &Options, StringRef LocalName, StringRef Value) const
Stores an option with the check-local name LocalName with string value Value to Options.
Base class for all clang-tidy checks.
DiagnosticBuilder diag(SourceLocation Loc, StringRef Description, DiagnosticIDs::Level Level=DiagnosticIDs::Warning)
Add a diagnostic with the check's name.
const LangOptions & getLangOpts() const
Returns the language options from the context.
Every ClangTidyCheck reports errors through a DiagnosticsEngine provided by this context.
void registerMatchers(ast_matchers::MatchFinder *Finder) override
Override this to register AST matchers with Finder.
NamespaceCommentCheck(StringRef Name, ClangTidyContext *Context)
void check(const ast_matchers::MatchFinder::MatchResult &Result) override
ClangTidyChecks that register ASTMatchers should do the actual work in here.
static std::optional< std::string > getNamespaceNameAsWritten(SourceLocation &Loc, const SourceManager &Sources, const LangOptions &LangOpts)
static bool locationsInSameFile(const SourceManager &Sources, SourceLocation Loc1, SourceLocation Loc2)
std::optional< Token > findNextTokenSkippingComments(SourceLocation Start, const SourceManager &SM, const LangOptions &LangOpts)
Definition: LexerUtils.cpp:111
Some operations such as code completion produce a set of candidates.
llvm::StringMap< ClangTidyValue > OptionMap