clang-tools  9.0.0
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 "clang/AST/ASTContext.h"
11 #include "clang/ASTMatchers/ASTMatchers.h"
12 #include "clang/Basic/SourceLocation.h"
13 #include "clang/Lex/Lexer.h"
14 #include "llvm/ADT/StringExtras.h"
15 
16 using namespace clang::ast_matchers;
17 
18 namespace clang {
19 namespace tidy {
20 namespace readability {
21 
22 NamespaceCommentCheck::NamespaceCommentCheck(StringRef Name,
23  ClangTidyContext *Context)
24  : ClangTidyCheck(Name, Context),
25  NamespaceCommentPattern("^/[/*] *(end (of )?)? *(anonymous|unnamed)? *"
26  "namespace( +([a-zA-Z0-9_:]+))?\\.? *(\\*/)?$",
27  llvm::Regex::IgnoreCase),
28  ShortNamespaceLines(Options.get("ShortNamespaceLines", 1u)),
29  SpacesBeforeComments(Options.get("SpacesBeforeComments", 1u)) {}
30 
31 void NamespaceCommentCheck::storeOptions(ClangTidyOptions::OptionMap &Opts) {
32  Options.store(Opts, "ShortNamespaceLines", ShortNamespaceLines);
33  Options.store(Opts, "SpacesBeforeComments", SpacesBeforeComments);
34 }
35 
36 void NamespaceCommentCheck::registerMatchers(MatchFinder *Finder) {
37  // Only register the matchers for C++; the functionality currently does not
38  // provide any benefit to other languages, despite being benign.
39  if (getLangOpts().CPlusPlus)
40  Finder->addMatcher(namespaceDecl().bind("namespace"), this);
41 }
42 
43 static bool locationsInSameFile(const SourceManager &Sources,
44  SourceLocation Loc1, SourceLocation Loc2) {
45  return Loc1.isFileID() && Loc2.isFileID() &&
46  Sources.getFileID(Loc1) == Sources.getFileID(Loc2);
47 }
48 
49 static std::string getNamespaceComment(const NamespaceDecl *ND,
50  bool InsertLineBreak) {
51  std::string Fix = "// namespace";
52  if (!ND->isAnonymousNamespace())
53  Fix.append(" ").append(ND->getNameAsString());
54  if (InsertLineBreak)
55  Fix.append("\n");
56  return Fix;
57 }
58 
59 static std::string getNamespaceComment(const std::string &NameSpaceName,
60  bool InsertLineBreak) {
61  std::string Fix = "// namespace ";
62  Fix.append(NameSpaceName);
63  if (InsertLineBreak)
64  Fix.append("\n");
65  return Fix;
66 }
67 
68 void NamespaceCommentCheck::check(const MatchFinder::MatchResult &Result) {
69  const auto *ND = Result.Nodes.getNodeAs<NamespaceDecl>("namespace");
70  const SourceManager &Sources = *Result.SourceManager;
71 
72  if (!locationsInSameFile(Sources, ND->getBeginLoc(), ND->getRBraceLoc()))
73  return;
74 
75  // Don't require closing comments for namespaces spanning less than certain
76  // number of lines.
77  unsigned StartLine = Sources.getSpellingLineNumber(ND->getBeginLoc());
78  unsigned EndLine = Sources.getSpellingLineNumber(ND->getRBraceLoc());
79  if (EndLine - StartLine + 1 <= ShortNamespaceLines)
80  return;
81 
82  // Find next token after the namespace closing brace.
83  SourceLocation AfterRBrace = ND->getRBraceLoc().getLocWithOffset(1);
84  SourceLocation Loc = AfterRBrace;
85  Token Tok;
86  SourceLocation LBracketLocation = ND->getLocation();
87  SourceLocation NestedNamespaceBegin = LBracketLocation;
88 
89  // Currently for nested namepsace (n1::n2::...) the AST matcher will match foo
90  // then bar instead of a single match. So if we got a nested namespace we have
91  // to skip the next ones.
92  for (const auto &EndOfNameLocation : Ends) {
93  if (Sources.isBeforeInTranslationUnit(NestedNamespaceBegin,
94  EndOfNameLocation))
95  return;
96  }
97 
98  // Ignore macros
99  if (!ND->getLocation().isMacroID()) {
100  while (Lexer::getRawToken(LBracketLocation, Tok, Sources, getLangOpts()) ||
101  !Tok.is(tok::l_brace)) {
102  LBracketLocation = LBracketLocation.getLocWithOffset(1);
103  }
104  }
105 
106  // FIXME: This probably breaks on comments between the namespace and its '{'.
107  auto TextRange =
108  Lexer::getAsCharRange(SourceRange(NestedNamespaceBegin, LBracketLocation),
109  Sources, getLangOpts());
110  StringRef NestedNamespaceName =
111  Lexer::getSourceText(TextRange, Sources, getLangOpts())
112  .rtrim('{') // Drop the { itself.
113  .rtrim(); // Drop any whitespace before it.
114  bool IsNested = NestedNamespaceName.contains(':');
115 
116  if (IsNested)
117  Ends.push_back(LBracketLocation);
118  else
119  NestedNamespaceName = ND->getName();
120 
121  // Skip whitespace until we find the next token.
122  while (Lexer::getRawToken(Loc, Tok, Sources, getLangOpts()) ||
123  Tok.is(tok::semi)) {
124  Loc = Loc.getLocWithOffset(1);
125  }
126 
127  if (!locationsInSameFile(Sources, ND->getRBraceLoc(), Loc))
128  return;
129 
130  bool NextTokenIsOnSameLine = Sources.getSpellingLineNumber(Loc) == EndLine;
131  // If we insert a line comment before the token in the same line, we need
132  // to insert a line break.
133  bool NeedLineBreak = NextTokenIsOnSameLine && Tok.isNot(tok::eof);
134 
135  SourceRange OldCommentRange(AfterRBrace, AfterRBrace);
136  std::string Message = "%0 not terminated with a closing comment";
137 
138  // Try to find existing namespace closing comment on the same line.
139  if (Tok.is(tok::comment) && NextTokenIsOnSameLine) {
140  StringRef Comment(Sources.getCharacterData(Loc), Tok.getLength());
141  SmallVector<StringRef, 7> Groups;
142  if (NamespaceCommentPattern.match(Comment, &Groups)) {
143  StringRef NamespaceNameInComment = Groups.size() > 5 ? Groups[5] : "";
144  StringRef Anonymous = Groups.size() > 3 ? Groups[3] : "";
145 
146  if (IsNested && NestedNamespaceName == NamespaceNameInComment) {
147  // C++17 nested namespace.
148  return;
149  } else if ((ND->isAnonymousNamespace() &&
150  NamespaceNameInComment.empty()) ||
151  (ND->getNameAsString() == NamespaceNameInComment &&
152  Anonymous.empty())) {
153  // Check if the namespace in the comment is the same.
154  // FIXME: Maybe we need a strict mode, where we always fix namespace
155  // comments with different format.
156  return;
157  }
158 
159  // Otherwise we need to fix the comment.
160  NeedLineBreak = Comment.startswith("/*");
161  OldCommentRange =
162  SourceRange(AfterRBrace, Loc.getLocWithOffset(Tok.getLength()));
163  Message =
164  (llvm::Twine(
165  "%0 ends with a comment that refers to a wrong namespace '") +
166  NamespaceNameInComment + "'")
167  .str();
168  } else if (Comment.startswith("//")) {
169  // Assume that this is an unrecognized form of a namespace closing line
170  // comment. Replace it.
171  NeedLineBreak = false;
172  OldCommentRange =
173  SourceRange(AfterRBrace, Loc.getLocWithOffset(Tok.getLength()));
174  Message = "%0 ends with an unrecognized comment";
175  }
176  // If it's a block comment, just move it to the next line, as it can be
177  // multi-line or there may be other tokens behind it.
178  }
179 
180  std::string NamespaceName =
181  ND->isAnonymousNamespace()
182  ? "anonymous namespace"
183  : ("namespace '" + NestedNamespaceName.str() + "'");
184 
185  // Place diagnostic at an old comment, or closing brace if we did not have it.
186  SourceLocation DiagLoc =
187  OldCommentRange.getBegin() != OldCommentRange.getEnd()
188  ? OldCommentRange.getBegin()
189  : ND->getRBraceLoc();
190 
191  diag(DiagLoc, Message)
192  << NamespaceName
193  << FixItHint::CreateReplacement(
194  CharSourceRange::getCharRange(OldCommentRange),
195  std::string(SpacesBeforeComments, ' ') +
196  (IsNested
197  ? getNamespaceComment(NestedNamespaceName, NeedLineBreak)
198  : getNamespaceComment(ND, NeedLineBreak)));
199  diag(ND->getLocation(), "%0 starts here", DiagnosticIDs::Note)
200  << NamespaceName;
201 }
202 
203 } // namespace readability
204 } // namespace tidy
205 } // namespace clang
SourceLocation Loc
&#39;#&#39; location in the include directive
void registerMatchers(ast_matchers::MatchFinder *Finder) override
Override this to register AST matchers with Finder.
Some operations such as code completion produce a set of candidates.
constexpr llvm::StringLiteral Message
Base class for all clang-tidy checks.
const LangOptions & getLangOpts() const
Returns the language options from the context.
void check(const ast_matchers::MatchFinder::MatchResult &Result) override
ClangTidyChecks that register ASTMatchers should do the actual work in here.
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.
static bool locationsInSameFile(const SourceManager &Sources, SourceLocation Loc1, SourceLocation Loc2)
static constexpr llvm::StringLiteral Name
std::map< std::string, std::string > OptionMap
static std::string getNamespaceComment(const NamespaceDecl *ND, bool InsertLineBreak)
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Every ClangTidyCheck reports errors through a DiagnosticsEngine provided by this context.
llvm::Optional< llvm::Expected< tooling::AtomicChanges > > Result
Definition: Rename.cpp:36
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))
DiagnosticBuilder diag(SourceLocation Loc, StringRef Description, DiagnosticIDs::Level Level=DiagnosticIDs::Warning)
Add a diagnostic with the check&#39;s name.