[FileCheck] Fix code style of method comments

[thopre]

Summary

Fix various issues in code style of method comments:

1. Move all heading comments to all non-static methods near their declaration in the FileCheck.h header file.
2. Harmonize the action verb in doxygen comments for methods to always be in third person
3. Use \returns instead of free text "return" and "returns".
4. Document a couple more parameters while at it.

[probinson]

Thanks! Some small things, and LGTM once you've fixed those.

llvm/include/llvm/Support/FileCheck.h

257 ↗

(On Diff #197795)

I thought \p has to name the parameter? so "whether \p C is..."

271 ↗

(On Diff #197795)

What does "the Pattern" mean? There's no member or parameter named Pattern.

276 ↗

(On Diff #197795)

Parameter Req is not mentioned.

403 ↗

(On Diff #197795)

there are no

434 ↗

(On Diff #197795)

I could wish the parameters were described in detail, but that's beyond what you're doing in this patch.

446 ↗

(On Diff #197795)

No doc for Diags (but again won't insist for this patch).

[thopre]

• Document missing parameter beside SM in ReadCheckFile and CheckInput
• Add parameter name to description of isValidVarNameStart
• Rephrase comment for ParsePattern and document Req parameter

[thopre]

In D61445#1488086, @probinson wrote:

Thanks! Some small things, and LGTM once you've fixed those.

Since I've rephrased 2 comments and I'm not a native english speaker I'll let you (@probinson) review those changes. Only once you've acked them will I commit this patch. Thanks for the quick review!

[thopre]

Marking this patch as needing review to double check whether comment update in last version is intelligible and grammatically correct english

[probinson]

Sorry, I should have been more thorough about this previously: My understanding is that if a function description mentions any parameters with \p, then it needs to mention all of them.
For some of the one-liner descriptions, if you prefer to just remove the \p that's okay with me. You've been suffering a lot through this process and I don't want to create more work than we really need to!

llvm/include/llvm/Support/FileCheck.h

271 ↗

(On Diff #197931)

"initializes"

286 ↗

(On Diff #197931)

"\returns" describes the function return value, not the effect on other parameters. So:
\returns the position that ...
If there is a match, updates \p MatchLen with the size of the matched string.

318 ↗

(On Diff #197931)

Returns -> \returns

Description is missing parameter SM.

402 ↗

(On Diff #197931)

If you cite any parameters with \p you need to cite all of them.

404 ↗

(On Diff #197931)

If you cite any parameters with \p you need to cite all of them.

406 ↗

(On Diff #197931)

If you cite any parameters with \p you need to cite all of them.

438 ↗

(On Diff #197931)

Need to mention \p SM

451 ↗

(On Diff #197931)

Needs to cite \p SM

[thopre]

• Document parameters not mentioned in \p when others in the same function are mentioned
• Only use \returns for the return value

[probinson]

One or two last nits and LGTM.

llvm/include/llvm/Support/FileCheck.h

189 ↗

(On Diff #198701)

Depending on where this comes in the sequence of other patches, this might want to be "[#]VAR=VAL" (or not, if that syntax will be introduced after this patch, in which case ignore this comment).

439 ↗

(On Diff #198701)

record -> records

[thopre]

Use 3rd person for all verbs in ReadCheckFile comment

[probinson]

Still good.

llvm/trunk/include/llvm/Support/FileCheck.h

private:
   uint64_t Value;
 
 public:
   /// Constructor for a numeric expression with a known value at parse time,
   /// e.g. the implicit numeric expression defining the @LINE numeric pseudo
   /// variable.
   explicit FileCheckNumExpr(uint64_t Value) : Value(Value) {}
 
-  /// Return the value being matched against.
+  /// \returns the value being matched against.
   uint64_t getValue() const { return Value; }
 };
 
 class FileCheckPatternContext;
 
 /// Class representing a substitution to perform in the string to match.
 class FileCheckPatternSubstitution {
 private:
FileCheckPatternSubstitution(FileCheckPatternContext *Context,
         InsertIdx(InsertIdx) {}
 
   /// Constructor for a numeric expression substitution.
   FileCheckPatternSubstitution(FileCheckPatternContext *Context, StringRef Expr,
                                FileCheckNumExpr *NumExpr, size_t InsertIdx)
       : Context(Context), IsNumExpr(true), FromStr(Expr), NumExpr(NumExpr),
         InsertIdx(InsertIdx) {}
 
-  /// Return whether this is a numeric expression substitution.
+  /// \returns whether this is a numeric expression substitution.
   bool isNumExpr() const { return IsNumExpr; }
 
-  /// Return the string to be substituted.
+  /// \returns the string to be substituted.
   StringRef getFromString() const { return FromStr; }
 
-  /// Return the index where the substitution is to be performed.
+  /// \returns the index where the substitution is to be performed.
   size_t getIndex() const { return InsertIdx; }
 
-  /// Return the result of the substitution represented by this class instance
-  /// or None if substitution failed. For a numeric expression we substitute it
-  /// by its value. For a pattern variable we simply replace it by the text its
-  /// definition matched.
+  /// \returns the result of the substitution represented by this class
+  /// instance or None if substitution failed. For a numeric expression we
+  /// substitute it by its value. For a pattern variable we simply replace it
+  /// by the text its definition matched.
   llvm::Optional<std::string> getResult() const;
 
-  /// Return the name of the undefined variable used in this substitution, if
+  /// \returns the name of the undefined variable used in this substitution, if
   /// any, or an empty string otherwise.
   StringRef getUndefVarName() const;
 };
 
 //===----------------------------------------------------------------------===//
 // Pattern handling code.
 //===----------------------------------------------------------------------===//
 
public:
   FileCheckType(FileCheckKind Kind = CheckNone) : Kind(Kind), Count(1) {}
   FileCheckType(const FileCheckType &) = default;
 
   operator FileCheckKind() const { return Kind; }
 
   int getCount() const { return Count; }
   FileCheckType &setCount(int C);
 
+  // \returns a description of \p Prefix.
   std::string getDescription(StringRef Prefix) const;
 };
 } // namespace Check
 
 struct FileCheckDiag;
 
 /// Class holding the FileCheckPattern global state, shared by all patterns:
 /// tables holding values of variables and whether they are defined or not at
private:
   StringMap<StringRef> GlobalVariableTable;
 
   /// Vector holding pointers to all parsed numeric expressions. Used to
   /// automatically free the numeric expressions once they are guaranteed to no
   /// longer be used.
   std::vector<std::unique_ptr<FileCheckNumExpr>> NumExprs;
 
 public:
-  /// Return the value of pattern variable \p VarName or None if no such
+  /// \returns the value of pattern variable \p VarName or None if no such
   /// variable has been defined.
   llvm::Optional<StringRef> getPatternVarValue(StringRef VarName);
 
-  /// Define pattern variables from definitions given on the command line,
-  /// passed as a vector of VAR=VAL strings in \p CmdlineDefines. Report any
-  /// error to \p SM and return whether an error occured.
+  /// Defines pattern variables from definitions given on the command line,
+  /// passed as a vector of VAR=VAL strings in \p CmdlineDefines. Reports any
+  /// error to \p SM and \returns whether an error occured.
   bool defineCmdlineVariables(std::vector<std::string> &CmdlineDefines,
                               SourceMgr &SM);
 
-  /// Undefine local variables (variables whose name does not start with a '$'
-  /// sign), i.e. remove them from GlobalVariableTable.
+  /// Undefines local variables (variables whose name does not start with a '$'
+  /// sign), i.e. removes them from GlobalVariableTable.
   void clearLocalVars();
 
 private:
-  /// Make a new numeric expression instance and register it for destruction
+  /// Makes a new numeric expression instance and registers it for destruction
   /// when the context is destroyed.
   template <class... Types> FileCheckNumExpr *makeNumExpr(Types... Args);
 };
 
 class FileCheckPattern {
   SMLoc PatternLoc;
 
   /// A fixed string to match as the pattern or empty if this pattern requires
class FileCheckPattern {
   /// Contains the number of line this pattern is in.
   unsigned LineNumber;
 
 public:
   explicit FileCheckPattern(Check::FileCheckType Ty,
                             FileCheckPatternContext *Context)
       : Context(Context), CheckTy(Ty) {}
 
-  /// Returns the location in source code.
+  /// \returns the location in source code.
   SMLoc getLoc() const { return PatternLoc; }
 
-  /// Returns the pointer to the global state for all patterns in this
+  /// \returns the pointer to the global state for all patterns in this
   /// FileCheck instance.
   FileCheckPatternContext *getContext() const { return Context; }
 
-  /// Return whether \p is a valid first character for a variable name.
+  /// \returns whether \p C is a valid first character for a variable name.
   static bool isValidVarNameStart(char C);
-  /// Verify that the string at the start of \p Str is a well formed variable.
-  /// Return false if it is and set \p IsPseudo to indicate if it is a pseudo
-  /// variable and \p TrailIdx to the position of the last character that is
-  /// part of the variable name. Otherwise, only return true.
+  /// Verifies that the string at the start of \p Str is a well formed
+  /// variable. \returns false if it is and sets \p IsPseudo to indicate if it
+  /// is a pseudo variable and \p TrailIdx to the position of the last
+  /// character that is part of the variable name. Otherwise, only
+  /// \returns true.
   static bool parseVariable(StringRef Str, bool &IsPseudo, unsigned &TrailIdx);
-  /// Parse a numeric expression involving pseudo variable \p Name with the
+  /// Parses a numeric expression involving pseudo variable \p Name with the
   /// string corresponding to the operation being performed in \p Trailer.
-  /// Return the class representing the numeric expression or nullptr if
+  /// \returns the class representing the numeric expression or nullptr if
   /// parsing fails in which case errors are reported on \p SM.
   FileCheckNumExpr *parseNumericExpression(StringRef Name, StringRef Trailer,
                                            const SourceMgr &SM) const;
+  /// Parses the pattern in \p PatternStr and initializes this FileCheckPattern
+  /// instance accordingly.
+  ///
+  /// \p Prefix provides which prefix is being matched, \p Req describes the
+  /// global options that influence the parsing such as whitespace
+  /// canonicalization, \p SM provides the SourceMgr used for error reports,
+  /// and \p LineNumber is the line number in the input file from which the
+  /// pattern string was read. \returns true in case of an error, false
+  /// otherwise.
   bool ParsePattern(StringRef PatternStr, StringRef Prefix, SourceMgr &SM,
                     unsigned LineNumber, const FileCheckRequest &Req);
+  /// Matches the pattern string against the input buffer \p Buffer
+  ///
+  /// \returns the position that is matched or npos if there is no match. If
+  /// there is a match, updates \p MatchLen with the size of the matched
+  /// string.
+  ///
+  /// The GlobalVariableTable StringMap in the FileCheckPatternContext class
+  /// instance provides the current values of FileCheck pattern variables and
+  /// is updated if this match defines new values.
   size_t match(StringRef Buffer, size_t &MatchLen) const;
-  /// Print value of successful substitutions or name of undefined pattern or
-  /// numeric variables preventing such a successful substitution.
+  /// Prints the value of successful substitutions or the name of the undefined
+  /// pattern or numeric variable preventing such a successful substitution.
   void printSubstitutions(const SourceMgr &SM, StringRef Buffer,
                           SMRange MatchRange = None) const;
   void printFuzzyMatch(const SourceMgr &SM, StringRef Buffer,
                        std::vector<FileCheckDiag> *Diags) const;
 
   bool hasVariable() const {
     return !(Substitutions.empty() && VariableDefs.empty());
   }
 
   Check::FileCheckType getCheckTy() const { return CheckTy; }
 
   int getCount() const { return CheckTy.getCount(); }
 
 private:
   bool AddRegExToRegEx(StringRef RS, unsigned &CurParen, SourceMgr &SM);
   void AddBackrefToRegEx(unsigned BackrefNum);
+  /// Computes an arbitrary estimate for the quality of matching this pattern
+  /// at the start of \p Buffer; a distance of zero should correspond to a
+  /// perfect match.
   unsigned computeMatchDistance(StringRef Buffer) const;
+  /// Finds the closing sequence of a regex variable usage or definition.
+  ///
+  /// \p Str has to point in the beginning of the definition (right after the
+  /// opening sequence). \p SM holds the SourceMgr used for error repporting.
+  ///  \returns the offset of the closing sequence within Str, or npos if it
+  /// was not found.
   size_t FindRegexVarEnd(StringRef Str, SourceMgr &SM);
 };
 
 //===----------------------------------------------------------------------===//
 /// Summary of a FileCheck diagnostic.
 //===----------------------------------------------------------------------===//
 
 struct FileCheckDiag {
struct FileCheckString {
 
   /// All of the strings that are disallowed from occurring between this match
   /// string and the previous one (or start of file).
   std::vector<FileCheckPattern> DagNotStrings;
 
   FileCheckString(const FileCheckPattern &P, StringRef S, SMLoc L)
       : Pat(P), Prefix(S), Loc(L) {}
 
+  /// Matches check string and its "not strings" and/or "dag strings".
   size_t Check(const SourceMgr &SM, StringRef Buffer, bool IsLabelScanMode,
                size_t &MatchLen, FileCheckRequest &Req,
                std::vector<FileCheckDiag> *Diags) const;
 
+  /// Verifies that there is a single line in the given \p Buffer. Errors are
+  /// reported against \p SM.
   bool CheckNext(const SourceMgr &SM, StringRef Buffer) const;
+  /// Verifies that there is no newline in the given \p Buffer. Errors are
+  /// reported against \p SM.
   bool CheckSame(const SourceMgr &SM, StringRef Buffer) const;
+  /// Verifies that none of the strings in \p NotStrings are found in the given
+  /// \p Buffer. Errors are reported against \p SM and diagnostics recorded in
+  /// \p Diags according to the verbosity level set in \p Req.
   bool CheckNot(const SourceMgr &SM, StringRef Buffer,
                 const std::vector<const FileCheckPattern *> &NotStrings,
                 const FileCheckRequest &Req,
                 std::vector<FileCheckDiag> *Diags) const;
+  /// Matches "dag strings" and their mixed "not strings".
   size_t CheckDag(const SourceMgr &SM, StringRef Buffer,
                   std::vector<const FileCheckPattern *> &NotStrings,
                   const FileCheckRequest &Req,
                   std::vector<FileCheckDiag> *Diags) const;
 };
 
 /// FileCheck class takes the request and exposes various methods that
 /// use information from the request.
 class FileCheck {
   FileCheckRequest Req;
   FileCheckPatternContext PatternContext;
 
 public:
   FileCheck(FileCheckRequest Req) : Req(Req) {}
 
   // Combines the check prefixes into a single regex so that we can efficiently
   // scan for any of the set.
   //
   // The semantics are that the longest-match wins which matches our regex
   // library.
   Regex buildCheckPrefixRegex();
 
-  /// Read the check file, which specifies the sequence of expected strings.
+  /// Reads the check file from \p Buffer and records the expected strings it
+  /// contains in the \p CheckStrings vector. Errors are reported against
+  /// \p SM.
   ///
-  /// The strings are added to the CheckStrings vector. Returns true in case of
-  /// an error, false otherwise.
+  /// Only expected strings whose prefix is one of those listed in \p PrefixRE
+  /// are recorded. \returns true in case of an error, false otherwise.
   bool ReadCheckFile(SourceMgr &SM, StringRef Buffer, Regex &PrefixRE,
                      std::vector<FileCheckString> &CheckStrings);
 
   bool ValidateCheckPrefixes();
 
-  /// Canonicalize whitespaces in the file. Line endings are replaced with
+  /// Canonicalizes whitespaces in the file. Line endings are replaced with
   /// UNIX-style '\n'.
   StringRef CanonicalizeFile(MemoryBuffer &MB,
                              SmallVectorImpl<char> &OutputBuffer);
 
-  /// Check the input to FileCheck provided in the \p Buffer against the \p
-  /// CheckStrings read from the check file.
+  /// Checks the input to FileCheck provided in the \p Buffer against the
+  /// \p CheckStrings read from the check file and record diagnostics emitted
+  /// in \p Diags. Errors are recorded against \p SM.
   ///
-  /// Returns false if the input fails to satisfy the checks.
+  /// \returns false if the input fails to satisfy the checks.
   bool CheckInput(SourceMgr &SM, StringRef Buffer,
                   ArrayRef<FileCheckString> CheckStrings,
                   std::vector<FileCheckDiag> *Diags = nullptr);
 };
 } // namespace llvm
 #endif

llvm/trunk/lib/Support/FileCheck.cpp

default:
     SM.PrintMessage(OpLoc, SourceMgr::DK_Error,
                     Twine("unsupported numeric operation '") + Twine(Operator) +
                         "'");
     return nullptr;
   }
   return Context->makeNumExpr(Value);
 }
 
-/// Parses the given string into the Pattern.
-///
-/// \p Prefix provides which prefix is being matched, \p SM provides the
-/// SourceMgr used for error reports, and \p LineNumber is the line number in
-/// the input file from which the pattern string was read. Returns true in
-/// case of an error, false otherwise.
 bool FileCheckPattern::ParsePattern(StringRef PatternStr, StringRef Prefix,
                            SourceMgr &SM, unsigned LineNumber,
                            const FileCheckRequest &Req) {
   bool MatchFullLinesHere = Req.MatchFullLines && CheckTy != Check::CheckNot;
 
   this->LineNumber = LineNumber;
   PatternLoc = SMLoc::getFromPointer(PatternStr.data());
 

 }
 
 void FileCheckPattern::AddBackrefToRegEx(unsigned BackrefNum) {
   assert(BackrefNum >= 1 && BackrefNum <= 9 && "Invalid backref number");
   std::string Backref = std::string("\\") + std::string(1, '0' + BackrefNum);
   RegExStr += Backref;
 }
 
-/// Matches the pattern string against the input buffer \p Buffer
-///
-/// This returns the position that is matched or npos if there is no match. If
-/// there is a match, the size of the matched string is returned in \p
-/// MatchLen.
-///
-/// The GlobalVariableTable StringMap in the FileCheckPatternContext class
-/// instance provides the current values of FileCheck pattern variables and is
-/// updated if this match defines new values.
 size_t FileCheckPattern::match(StringRef Buffer, size_t &MatchLen) const {
   // If this is the EOF pattern, match it immediately.
   if (CheckTy == Check::CheckEOF) {
     MatchLen = 0;
     return Buffer.size();
   }
 
   // If this is a fixed string pattern, just match it now.
size_t FileCheckPattern::match(StringRef Buffer, size_t &MatchLen) const {
   // Like CHECK-NEXT, CHECK-EMPTY's match range is considered to start after
   // the required preceding newline, which is consumed by the pattern in the
   // case of CHECK-EMPTY but not CHECK-NEXT.
   size_t MatchStartSkip = CheckTy == Check::CheckEmpty;
   MatchLen = FullMatch.size() - MatchStartSkip;
   return FullMatch.data() - Buffer.data() + MatchStartSkip;
 }
 
-/// Computes an arbitrary estimate for the quality of matching this pattern at
-/// the start of \p Buffer; a distance of zero should correspond to a perfect
-/// match.
 unsigned FileCheckPattern::computeMatchDistance(StringRef Buffer) const {
   // Just compute the number of matching characters. For regular expressions, we
   // just compare against the regex itself and hope for the best.
   //
   // FIXME: One easy improvement here is have the regex lib generate a single
   // example regular expression which matches, and use that as the example
   // string.
   StringRef ExampleString(FixedStr);

 }
 
 template <class... Types>
 FileCheckNumExpr *FileCheckPatternContext::makeNumExpr(Types... Args) {
   NumExprs.emplace_back(new FileCheckNumExpr(Args...));
   return NumExprs.back().get();
 }
 
-/// Finds the closing sequence of a regex variable usage or definition.
-///
-/// \p Str has to point in the beginning of the definition (right after the
-/// opening sequence). Returns the offset of the closing sequence within Str,
-/// or npos if it was not found.
 size_t FileCheckPattern::FindRegexVarEnd(StringRef Str, SourceMgr &SM) {
   // Offset keeps track of the current offset within the input Str
   size_t Offset = 0;
   // [...] Nesting depth
   size_t BracketDepth = 0;
 
   while (!Str.empty()) {
     if (Str.startswith("]]") && BracketDepth == 0)
if (Str[0] == '\\') {
       Str = Str.substr(1);
       Offset++;
     }
   }
 
   return StringRef::npos;
 }
 
-/// Canonicalize whitespaces in the file. Line endings are replaced with
-/// UNIX-style '\n'.
 StringRef
 llvm::FileCheck::CanonicalizeFile(MemoryBuffer &MB,
                                   SmallVectorImpl<char> &OutputBuffer) {
   OutputBuffer.reserve(MB.getBufferSize());
 
   for (const char *Ptr = MB.getBufferStart(), *End = MB.getBufferEnd();
        Ptr != End; ++Ptr) {
     // Eliminate trailing dosish \r.

 Check::FileCheckType &Check::FileCheckType::setCount(int C) {
   assert(Count > 0 && "zero and negative counts are not supported");
   assert((C == 1 || Kind == CheckPlain) &&
          "count supported only for plain CHECK directives");
   Count = C;
   return *this;
 }
 
-// Get a description of the type.
 std::string Check::FileCheckType::getDescription(StringRef Prefix) const {
   switch (Kind) {
   case Check::CheckNone:
     return "invalid";
   case Check::CheckPlain:
     if (Count > 1)
       return Prefix.str() + "-COUNT";
     return Prefix;

 
 // From the given position, find the next character after the word.
 static size_t SkipWord(StringRef Str, size_t Loc) {
   while (Loc < Str.size() && IsPartOfWord(Str[Loc]))
     ++Loc;
   return Loc;
 }
 
-/// Search the buffer for the first prefix in the prefix regular expression.
+/// Searches the buffer for the first prefix in the prefix regular expression.
 ///
 /// This searches the buffer using the provided regular expression, however it
 /// enforces constraints beyond that:
 /// 1) The found prefix must not be a suffix of something that looks like
 ///    a valid prefix.
 /// 2) The found prefix must be followed by a valid check type suffix using \c
 ///    FindCheckType above.
 ///
-/// Returns a pair of StringRefs into the Buffer, which combines:
+/// \returns a pair of StringRefs into the Buffer, which combines:
 ///   - the first match of the regular expression to satisfy these two is
 ///   returned,
 ///     otherwise an empty StringRef is returned to indicate failure.
 ///   - buffer rewound to the location right after parsed suffix, for parsing
 ///     to continue from
 ///
 /// If this routine returns a valid prefix, it will also shrink \p Buffer to
 /// start at the beginning of the returned prefix, increment \p LineNumber for
while (!Buffer.empty()) {
     // matched and any additional parts of that check-like word.
     Buffer = Buffer.drop_front(SkipWord(Buffer, Prefix.size()));
   }
 
   // We ran out of buffer while skipping partial matches so give up.
   return {StringRef(), StringRef()};
 }
 
-/// Read the check file, which specifies the sequence of expected strings.
-///
-/// The strings are added to the CheckStrings vector. Returns true in case of
-/// an error, false otherwise.
 bool llvm::FileCheck::ReadCheckFile(
     SourceMgr &SM, StringRef Buffer, Regex &PrefixRE,
     std::vector<FileCheckString> &CheckStrings) {
   if (PatternContext.defineCmdlineVariables(Req.GlobalDefines, SM))
     return true;
 
   std::vector<FileCheckPattern> ImplicitNegativeChecks;
   for (const auto &PatternString : Req.ImplicitCheckNot) {

 static void PrintNoMatch(bool ExpectedMatch, const SourceMgr &SM,
                          const FileCheckString &CheckStr, int MatchedCount,
                          StringRef Buffer, bool VerboseVerbose,
                          std::vector<FileCheckDiag> *Diags) {
   PrintNoMatch(ExpectedMatch, SM, CheckStr.Prefix, CheckStr.Loc, CheckStr.Pat,
                MatchedCount, Buffer, VerboseVerbose, Diags);
 }
 
-/// Count the number of newlines in the specified range.
+/// Counts the number of newlines in the specified range.
 static unsigned CountNumNewlinesBetween(StringRef Range,
                                         const char *&FirstNewLine) {
   unsigned NumNewLines = 0;
   while (1) {
     // Scan for newline.
     Range = Range.substr(Range.find_first_of("\n\r"));
     if (Range.empty())
       return NumNewLines;
 
     ++NumNewLines;
 
     // Handle \n\r and \r\n as a single newline.
     if (Range.size() > 1 && (Range[1] == '\n' || Range[1] == '\r') &&
         (Range[0] != Range[1]))
       Range = Range.substr(1);
     Range = Range.substr(1);
 
     if (NumNewLines == 1)
       FirstNewLine = Range.begin();
   }
 }
 
-/// Match check string and its "not strings" and/or "dag strings".
 size_t FileCheckString::Check(const SourceMgr &SM, StringRef Buffer,
                               bool IsLabelScanMode, size_t &MatchLen,
                               FileCheckRequest &Req,
                               std::vector<FileCheckDiag> *Diags) const {
   size_t LastPos = 0;
   std::vector<const FileCheckPattern *> NotStrings;
 
   // IsLabelScanMode is true when we are scanning forward to find CHECK-LABEL
if (!IsLabelScanMode) {
     // skipped region.
     if (CheckNot(SM, SkippedRegion, NotStrings, Req, Diags))
       return StringRef::npos;
   }
 
   return FirstMatchPos;
 }
 
-/// Verify there is a single line in the given buffer.
 bool FileCheckString::CheckNext(const SourceMgr &SM, StringRef Buffer) const {
   if (Pat.getCheckTy() != Check::CheckNext &&
       Pat.getCheckTy() != Check::CheckEmpty)
     return false;
 
   Twine CheckName =
       Prefix +
       Twine(Pat.getCheckTy() == Check::CheckEmpty ? "-EMPTY" : "-NEXT");
if (NumNewLines != 1) {
     SM.PrintMessage(SMLoc::getFromPointer(FirstNewLine), SourceMgr::DK_Note,
                     "non-matching line after previous match is here");
     return true;
   }
 
   return false;
 }
 
-/// Verify there is no newline in the given buffer.
 bool FileCheckString::CheckSame(const SourceMgr &SM, StringRef Buffer) const {
   if (Pat.getCheckTy() != Check::CheckSame)
     return false;
 
   // Count the number of newlines between the previous match and this one.
   const char *FirstNewLine = nullptr;
   unsigned NumNewLines = CountNumNewlinesBetween(Buffer, FirstNewLine);
 
   if (NumNewLines != 0) {
     SM.PrintMessage(Loc, SourceMgr::DK_Error,
                     Prefix +
                         "-SAME: is not on the same line as the previous match");
     SM.PrintMessage(SMLoc::getFromPointer(Buffer.end()), SourceMgr::DK_Note,
                     "'next' match was here");
     SM.PrintMessage(SMLoc::getFromPointer(Buffer.data()), SourceMgr::DK_Note,
                     "previous match ended here");
     return true;
   }
 
   return false;
 }
 
-/// Verify there's no "not strings" in the given buffer.
 bool FileCheckString::CheckNot(
     const SourceMgr &SM, StringRef Buffer,
     const std::vector<const FileCheckPattern *> &NotStrings,
     const FileCheckRequest &Req, std::vector<FileCheckDiag> *Diags) const {
   for (const FileCheckPattern *Pat : NotStrings) {
     assert((Pat->getCheckTy() == Check::CheckNot) && "Expect CHECK-NOT!");
 
     size_t MatchLen = 0;
PrintMatch(false, SM, Prefix, Pat->getLoc(), *Pat, 1, Buffer, Pos, MatchLen,
                Req, Diags);
 
     return true;
   }
 
   return false;
 }
 
-/// Match "dag strings" and their mixed "not strings".
 size_t
 FileCheckString::CheckDag(const SourceMgr &SM, StringRef Buffer,
                           std::vector<const FileCheckPattern *> &NotStrings,
                           const FileCheckRequest &Req,
                           std::vector<FileCheckDiag> *Diags) const {
   if (DagNotStrings.empty())
     return 0;
 
for (StringRef Prefix : Req.CheckPrefixes) {
 
     if (!ValidateCheckPrefix(Prefix))
       return false;
   }
 
   return true;
 }
 
-// Combines the check prefixes into a single regex so that we can efficiently
-// scan for any of the set.
-//
-// The semantics are that the longest-match wins which matches our regex
-// library.
 Regex llvm::FileCheck::buildCheckPrefixRegex() {
   // I don't think there's a way to specify an initial value for cl::list,
   // so if nothing was specified, add the default
   if (Req.CheckPrefixes.empty())
     Req.CheckPrefixes.push_back("CHECK");
 
   // We already validated the contents of CheckPrefixes so just concatenate
   // them as alternatives.
void FileCheckPatternContext::clearLocalVars() {
   for (const StringMapEntry<StringRef> &Var : GlobalVariableTable)
     if (Var.first()[0] != '$')
       LocalPatternVars.push_back(Var.first());
 
   for (const auto &Var : LocalPatternVars)
     GlobalVariableTable.erase(Var);
 }
 
-/// Check the input to FileCheck provided in the \p Buffer against the \p
-/// CheckStrings read from the check file.
-///
-/// Returns false if the input fails to satisfy the checks.
 bool llvm::FileCheck::CheckInput(SourceMgr &SM, StringRef Buffer,
                                  ArrayRef<FileCheckString> CheckStrings,
                                  std::vector<FileCheckDiag> *Diags) {
   bool ChecksFailed = false;
 
   unsigned i = 0, j = 0, e = CheckStrings.size();
   while (true) {
     StringRef CheckRegion;