clang-tools  14.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 
18 using namespace clang::ast_matchers;
19 
20 namespace clang {
21 namespace tidy {
22 namespace readability {
23 
24 NamespaceCommentCheck::NamespaceCommentCheck(StringRef Name,
25  ClangTidyContext *Context)
26  : ClangTidyCheck(Name, Context),
27  NamespaceCommentPattern("^/[/*] *(end (of )?)? *(anonymous|unnamed)? *"
28  "namespace( +([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 llvm::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 (llvm::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" && ID != "inline")
72  Result.append(std::string(ID));
73  } else if (T->is(tok::coloncolon)) {
74  Result.append("::");
75  } else { // Any other kind of token is unexpected here.
76  return llvm::None;
77  }
78  }
79  }
80  return Result;
81 }
82 
83 void NamespaceCommentCheck::check(const MatchFinder::MatchResult &Result) {
84  const auto *ND = Result.Nodes.getNodeAs<NamespaceDecl>("namespace");
85  const SourceManager &Sources = *Result.SourceManager;
86 
87  // Ignore namespaces inside macros and namespaces split across files.
88  if (ND->getBeginLoc().isMacroID() ||
89  !locationsInSameFile(Sources, ND->getBeginLoc(), ND->getRBraceLoc()))
90  return;
91 
92  // Don't require closing comments for namespaces spanning less than certain
93  // number of lines.
94  unsigned StartLine = Sources.getSpellingLineNumber(ND->getBeginLoc());
95  unsigned EndLine = Sources.getSpellingLineNumber(ND->getRBraceLoc());
96  if (EndLine - StartLine + 1 <= ShortNamespaceLines)
97  return;
98 
99  // Find next token after the namespace closing brace.
100  SourceLocation AfterRBrace = Lexer::getLocForEndOfToken(
101  ND->getRBraceLoc(), /*Offset=*/0, Sources, getLangOpts());
102  SourceLocation Loc = AfterRBrace;
103  SourceLocation LBraceLoc = ND->getBeginLoc();
104 
105  // Currently for nested namespace (n1::n2::...) the AST matcher will match foo
106  // then bar instead of a single match. So if we got a nested namespace we have
107  // to skip the next ones.
108  for (const auto &EndOfNameLocation : Ends) {
109  if (Sources.isBeforeInTranslationUnit(ND->getLocation(), EndOfNameLocation))
110  return;
111  }
112 
113  llvm::Optional<std::string> NamespaceNameAsWritten =
114  getNamespaceNameAsWritten(LBraceLoc, Sources, getLangOpts());
115  if (!NamespaceNameAsWritten)
116  return;
117 
118  if (NamespaceNameAsWritten->empty() != ND->isAnonymousNamespace()) {
119  // Apparently, we didn't find the correct namespace name. Give up.
120  return;
121  }
122 
123  Ends.push_back(LBraceLoc);
124 
125  Token Tok;
126  // Skip whitespace until we find the next token.
127  while (Lexer::getRawToken(Loc, Tok, Sources, getLangOpts()) ||
128  Tok.is(tok::semi)) {
129  Loc = Loc.getLocWithOffset(1);
130  }
131 
132  if (!locationsInSameFile(Sources, ND->getRBraceLoc(), Loc))
133  return;
134 
135  bool NextTokenIsOnSameLine = Sources.getSpellingLineNumber(Loc) == EndLine;
136  // If we insert a line comment before the token in the same line, we need
137  // to insert a line break.
138  bool NeedLineBreak = NextTokenIsOnSameLine && Tok.isNot(tok::eof);
139 
140  SourceRange OldCommentRange(AfterRBrace, AfterRBrace);
141  std::string Message = "%0 not terminated with a closing comment";
142 
143  // Try to find existing namespace closing comment on the same line.
144  if (Tok.is(tok::comment) && NextTokenIsOnSameLine) {
145  StringRef Comment(Sources.getCharacterData(Loc), Tok.getLength());
146  SmallVector<StringRef, 7> Groups;
147  if (NamespaceCommentPattern.match(Comment, &Groups)) {
148  StringRef NamespaceNameInComment = Groups.size() > 5 ? Groups[5] : "";
149  StringRef Anonymous = Groups.size() > 3 ? Groups[3] : "";
150 
151  if ((ND->isAnonymousNamespace() && NamespaceNameInComment.empty()) ||
152  (*NamespaceNameAsWritten == NamespaceNameInComment &&
153  Anonymous.empty())) {
154  // Check if the namespace in the comment is the same.
155  // FIXME: Maybe we need a strict mode, where we always fix namespace
156  // comments with different format.
157  return;
158  }
159 
160  // Otherwise we need to fix the comment.
161  NeedLineBreak = Comment.startswith("/*");
162  OldCommentRange =
163  SourceRange(AfterRBrace, Loc.getLocWithOffset(Tok.getLength()));
164  Message =
165  (llvm::Twine(
166  "%0 ends with a comment that refers to a wrong namespace '") +
167  NamespaceNameInComment + "'")
168  .str();
169  } else if (Comment.startswith("//")) {
170  // Assume that this is an unrecognized form of a namespace closing line
171  // comment. Replace it.
172  NeedLineBreak = false;
173  OldCommentRange =
174  SourceRange(AfterRBrace, Loc.getLocWithOffset(Tok.getLength()));
175  Message = "%0 ends with an unrecognized comment";
176  }
177  // If it's a block comment, just move it to the next line, as it can be
178  // multi-line or there may be other tokens behind it.
179  }
180 
181  std::string NamespaceNameForDiag =
182  ND->isAnonymousNamespace() ? "anonymous namespace"
183  : ("namespace '" + *NamespaceNameAsWritten + "'");
184 
185  std::string Fix(SpacesBeforeComments, ' ');
186  Fix.append("// namespace");
187  if (!ND->isAnonymousNamespace())
188  Fix.append(" ").append(*NamespaceNameAsWritten);
189  if (NeedLineBreak)
190  Fix.append("\n");
191 
192  // Place diagnostic at an old comment, or closing brace if we did not have it.
193  SourceLocation DiagLoc =
194  OldCommentRange.getBegin() != OldCommentRange.getEnd()
195  ? OldCommentRange.getBegin()
196  : ND->getRBraceLoc();
197 
198  diag(DiagLoc, Message) << NamespaceNameForDiag
199  << FixItHint::CreateReplacement(
200  CharSourceRange::getCharRange(OldCommentRange),
201  Fix);
202  diag(ND->getLocation(), "%0 starts here", DiagnosticIDs::Note)
203  << NamespaceNameForDiag;
204 }
205 
206 } // namespace readability
207 } // namespace tidy
208 } // namespace clang
clang::tidy::readability::NamespaceCommentCheck::registerMatchers
void registerMatchers(ast_matchers::MatchFinder *Finder) override
Override this to register AST matchers with Finder.
Definition: NamespaceCommentCheck.cpp:38
Loc
SourceLocation Loc
Definition: KernelNameRestrictionCheck.cpp:45
llvm
Some operations such as code completion produce a set of candidates.
Definition: YAMLGenerator.cpp:28
clang::tidy::ClangTidyOptions::OptionMap
llvm::StringMap< ClangTidyValue > OptionMap
Definition: ClangTidyOptions.h:115
clang::tidy::readability::getNamespaceNameAsWritten
static llvm::Optional< std::string > getNamespaceNameAsWritten(SourceLocation &Loc, const SourceManager &Sources, const LangOptions &LangOpts)
Definition: NamespaceCommentCheck.cpp:49
Nesting
const unsigned short Nesting
Definition: FunctionCognitiveComplexityCheck.cpp:92
clang::tidy::bugprone::Message
static const char Message[]
Definition: ReservedIdentifierCheck.cpp:31
clang::tidy::ClangTidyCheck
Base class for all clang-tidy checks.
Definition: ClangTidyCheck.h:54
Fix
static cl::opt< bool > Fix("fix", cl::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))
clang::tidy::readability::locationsInSameFile
static bool locationsInSameFile(const SourceManager &Sources, SourceLocation Loc1, SourceLocation Loc2)
Definition: NamespaceCommentCheck.cpp:42
clang::tidy::ClangTidyCheck::getLangOpts
const LangOptions & getLangOpts() const
Returns the language options from the context.
Definition: ClangTidyCheck.h:420
clang::ast_matchers
Definition: AbseilMatcher.h:14
clang::tidy::readability::NamespaceCommentCheck::check
void check(const ast_matchers::MatchFinder::MatchResult &Result) override
ClangTidyChecks that register ASTMatchers should do the actual work in here.
Definition: NamespaceCommentCheck.cpp:83
clang::tidy::ClangTidyCheck::Options
OptionsView Options
Definition: ClangTidyCheck.h:416
clang::tidy::ClangTidyContext
Every ClangTidyCheck reports errors through a DiagnosticsEngine provided by this context.
Definition: ClangTidyDiagnosticConsumer.h:72
Name
static constexpr llvm::StringLiteral Name
Definition: UppercaseLiteralSuffixCheck.cpp:28
clang::tidy::ClangTidyCheck::diag
DiagnosticBuilder diag(SourceLocation Loc, StringRef Description, DiagnosticIDs::Level Level=DiagnosticIDs::Warning)
Add a diagnostic with the check's name.
Definition: ClangTidyCheck.cpp:25
ID
static char ID
Definition: Logger.cpp:74
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
clang::tidy::ClangTidyCheck::OptionsView::store
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.
Definition: ClangTidyCheck.cpp:120
NamespaceCommentCheck.h
clang::tidy::utils::lexer::findNextTokenSkippingComments
Optional< Token > findNextTokenSkippingComments(SourceLocation Start, const SourceManager &SM, const LangOptions &LangOpts)
Definition: LexerUtils.cpp:80