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 
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
209