[clang-format] do not break before @tags in JS comments

[krasimir]

Summary

In JavaScript breaking before a @tag in a comment puts it on a new line, and
machinery that parses these comments will fail to understand such comments.

This adapts clang-format to not break before @. Similar functionality exists
for not breaking before {.

[krasimir]

clang/unittests/Format/FormatTestJS.cpp

194

this actually demonstrates a bug fixed by this patch: with 20 column limit, the comment should be split. The new behavior makes the test with a column limit of 25 redundant, so folded the two of them.

205

this is an exact duplicate as the check on old line 190; removed

[mprobst]

See my comment on the upstream bug, let's chat a bit about whether we need this.

[mprobst]

For posterity: there was a question whether this is legal syntax in JSDoc in the first place (e.g. whether it should be escaped). That remains unclear - Closure Compiler parser however does ignore JSDoc tags if the line does not start with an @ tag. So the safe thing is to do what this revision does, avoid wrapping.

clang/lib/Format/BreakableToken.cpp

while (SpaceOffset != StringRef::npos) {
 
     // Do not split before a number followed by a dot: this would be interpreted
     // as a numbered list, which would prevent re-flowing in subsequent passes.
     if (kNumberedListRegexp.match(Text.substr(SpaceOffset).ltrim(Blanks))) {
       SpaceOffset = Text.find_last_of(Blanks, SpaceOffset);
       continue;
     }
 
-    // Avoid ever breaking before a { in JavaScript.
+    // Avoid ever breaking before a @tag or a { in JavaScript.
     if (Style.Language == FormatStyle::LK_JavaScript &&
-        SpaceOffset + 1 < Text.size() && Text[SpaceOffset + 1] == '{') {
+        SpaceOffset + 1 < Text.size() &&
+        (Text[SpaceOffset + 1] == '{' || Text[SpaceOffset + 1] == '@')) {
       SpaceOffset = Text.find_last_of(Blanks, SpaceOffset);
       continue;
     }
 
     break;
   }
 
   if (SpaceOffset == StringRef::npos ||

clang/unittests/Format/FormatTestJS.cpp

EXPECT_EQ("function f() {\n"
                    getGoogleJSStyleWithColumns(20)));
 
   // Don't break the first line of a single line short jsdoc comment pragma.
   EXPECT_EQ("/** @returns j */",
             format("/** @returns j */", getGoogleJSStyleWithColumns(20)));
 
   // Break a single line long jsdoc comment pragma.
   EXPECT_EQ("/**\n"
-            " * @returns {string} jsdoc line 12\n"
-            " */",
-            format("/** @returns {string} jsdoc line 12 */",
-                   getGoogleJSStyleWithColumns(20)));
-  EXPECT_EQ("/**\n"
             " * @returns {string}\n"
             " *     jsdoc line 12\n"
             " */",
             format("/** @returns {string} jsdoc line 12 */",
-                   getGoogleJSStyleWithColumns(25)));
-
-  EXPECT_EQ("/**\n"
-            " * @returns {string} jsdoc line 12\n"
-            " */",
-            format("/** @returns {string} jsdoc line 12  */",
                    getGoogleJSStyleWithColumns(20)));
 
   // FIXME: this overcounts the */ as a continuation of the 12 when breaking.
   // Related to the FIXME in BreakableBlockComment::getRangeLength.
   EXPECT_EQ("/**\n"
             " * @returns {string}\n"
             " *     jsdoc line line\n"
             " *     12\n"
for (int ColumnLimit = 6; ColumnLimit < 13; ++ColumnLimit) {
     verifyFormat("/**\n"
                  " * @param {type}\n"
                  " */",
                  "/**\n"
                  " * @param {type}\n"
                  " */",
                  getGoogleJSStyleWithColumns(ColumnLimit));
   }
+  // don't break before @tags
+  verifyFormat("/**\n"
+               " * This\n"
+               " * tag @param\n"
+               " * stays.\n"
+               " */",
+               "/**\n"
+               " * This tag @param stays.\n"
+               " */",
+               getGoogleJSStyleWithColumns(13));
   verifyFormat("/**\n"
                " * @see http://very/very/long/url/is/long\n"
                " */",
                "/**\n"
                " * @see http://very/very/long/url/is/long\n"
                " */",
                getGoogleJSStyleWithColumns(20));
   verifyFormat("/**\n"