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 "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
206