Internal change

PiperOrigin-RevId: 512657926

Author: Closure Team

src/com/google/javascript/jscomp/parsing/Annotation.java

@@ -55,6 +55,7 @@ enum Annotation {
   MIXIN_CLASS,
   MIXIN_FUNCTION,
   MODIFIES,
+  MODS,
   NG_INJECT,
   NO_COLLAPSE,
   NO_COMPILE,
@@ -139,6 +140,7 @@ enum Annotation {
           .put("mixinClass", Annotation.MIXIN_CLASS)
           .put("mixinFunction", Annotation.MIXIN_FUNCTION)
           .put("modifies", Annotation.MODIFIES)
+          .put("mods", Annotation.MODS)
           .put("nocollapse", Annotation.NO_COLLAPSE)
           .put("nocompile", Annotation.NO_COMPILE)
           .put("nodts", Annotation.NO_DTS)

src/com/google/javascript/jscomp/parsing/JsDocInfoParser.java

@@ -549,6 +549,17 @@ private JsDocToken parseAnnotation(JsDocToken token, List<ExtendedTypeInfo> exte
           jsdocBuilder.recordEnhance(enhance);
           return token;
 
+        case MODS:
+          if (jsdocBuilder.isModsRecorded()) {
+            addParserWarning(Msg.JSDOC_MODS_EXTRA);
+          } else {
+            token = parseModsTag(next());
+          }
+          if (token != JsDocToken.EOC && token != JsDocToken.EOF) {
+            token = eatUntilEOLIfNotAnnotation();
+          }
+          return token;
+
         case ENUM:
           token = next();
           lineno = stream.getLineno();
@@ -1339,6 +1350,31 @@ private JsDocToken parseSuppressTag(JsDocToken token) {
     }
   }
 
+  /**
+   * Parse a {@code @mods} tag of the form {@code @mods &#123;google3.path.to.file&#125;}.
+   *
+   * @param token The current token.
+   */
+  private JsDocToken parseModsTag(JsDocToken token) {
+    if (token != JsDocToken.LEFT_CURLY) {
+      addParserWarning(Msg.JSDOC_MODS);
+      return token;
+    }
+    if (!match(JsDocToken.STRING)) {
+      addParserWarning(Msg.JSDOC_MODS);
+      return token;
+    }
+    String namespace = stream.getString();
+    token = next();
+    if (!match(JsDocToken.RIGHT_CURLY)) {
+      addParserWarning(Msg.JSDOC_MODS);
+    } else {
+      token = next();
+      jsdocBuilder.recordMods(namespace);
+    }
+    return token;
+  }
+
   /**
    * Parse a {@code @closurePrimitive} tag
    *

src/com/google/javascript/rhino/JSDocInfo.java

@@ -50,6 +50,7 @@
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
 import com.google.common.collect.Iterables;
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import java.io.Serializable;
 import java.util.ArrayList;
 import java.util.Collection;
@@ -486,6 +487,7 @@ private enum IdGenerator {
       new Property<>("fileoverviewDescription");
   private static final Property<String> RETURN_DESCRIPTION = new Property<>("returnDescription");
   private static final Property<String> ENHANCED_NAMESPACE = new Property<>("enhance");
+  private static final Property<String> MODS = new Property<>("mods");
   private static final Property<List<String>> TS_TYPES = new Property<>("tsType");
 
   private static final Property<List<String>> AUTHORS = new Property<>("authors");
@@ -1373,6 +1375,16 @@ public String getEnhance() {
     return ENHANCED_NAMESPACE.get(this);
   }
 
+  /** Returns whether this has a modded namespace. */
+  public boolean hasMods() {
+    return MODS.get(this) != null;
+  }
+
+  /** Returns the modded namespace or null if none is specified. */
+  public String getMods() {
+    return MODS.get(this);
+  }
+
   /** Gets the list of all markers for the documentation in this JSDoc. */
   public Collection<Marker> getMarkers() {
     ArrayList<Marker> markers = MARKERS.get(this);
@@ -1624,13 +1636,14 @@ public void recordOriginalCommentPosition(int position) {
      */
     public boolean isPopulatedWithFileOverview() {
       return populated
-          && (bits
-                  & (Bit.FILEOVERVIEW.mask
-                      | Bit.EXTERNS.mask
-                      | Bit.NOCOMPILE.mask
-                      | Bit.TYPE_SUMMARY.mask
-                      | Bit.ENHANCED_NAMESPACE.mask))
-              != 0;
+          && ((bits
+                      & (Bit.FILEOVERVIEW.mask
+                          | Bit.EXTERNS.mask
+                          | Bit.NOCOMPILE.mask
+                          | Bit.TYPE_SUMMARY.mask
+                          | Bit.ENHANCED_NAMESPACE.mask))
+                  != 0
+              || isModsRecorded());
     }
 
     /** Returns whether this builder recorded a description. */
@@ -2207,6 +2220,21 @@ public boolean recordEnhance(String namespace) {
       return populateProp(ENHANCED_NAMESPACE, namespace);
     }
 
+    /** Returns whether this builder recorded a modded namespace. */
+    public boolean isModsRecorded() {
+      return props.get(MODS) != null;
+    }
+
+    /**
+     * Records modded namespace.
+     *
+     * @return {@code true} If the modded namespace was recorded.
+     */
+    @CanIgnoreReturnValue
+    public boolean recordMods(String namespace) {
+      return populateProp(MODS, RhinoStringPool.addOrGet(namespace));
+    }
+
     public boolean recordLicense(String license) {
       setProp(LICENSE, RhinoStringPool.addOrGet(license));
       populated = true;

src/com/google/javascript/rhino/Msg.java

@@ -102,6 +102,8 @@ public enum Msg {
   JSDOC_MODIFIES("malformed @modifies tag"),
   JSDOC_MODIFIES_DUPLICATE("conflicting @modifies tag"),
   JSDOC_MODIFIES_UNKNOWN("unknown @modifies parameter: {0}"),
+  JSDOC_MODS("malformed @mods tag"),
+  JSDOC_MODS_EXTRA("extra @mods tag"),
   JSDOC_NAME_SYNTAX("name not recognized due to syntax error."),
   JSDOC_NGINJECT_EXTRA("extra @ngInject tag"),
   JSDOC_NOCOLLAPSE("extra @nocollapse tag"),

test/com/google/javascript/jscomp/parsing/JsDocInfoParserTest.java

@@ -2996,6 +2996,59 @@ public void testBadSuppress8() {
     parse("@suppress */", "malformed @suppress tag");
   }
 
+  @Test
+  public void testMods1() {
+    JSDocInfo info = parseFileOverview("@mods {ns.Foo} */");
+    assertThat(info.getMods()).isEqualTo("ns.Foo");
+  }
+
+  @Test
+  public void testMods2() {
+    JSDocInfo info = parseFileOverview("@mods {google3.path.to.file} */");
+    assertThat(info.getMods()).isEqualTo("google3.path.to.file");
+  }
+
+  @Test
+  public void testJsDocAfterMods() {
+    JSDocInfo info = parseFileOverview("@mods {ns.Foo} @modName {new_feature_flag} */");
+    assertThat(info.getMods()).isEqualTo("ns.Foo");
+  }
+
+  @Test
+  public void testMultipleModsTags() {
+    parseFileOverview("@mods {ns.Foo} \n * @mods {ns.Bar} */", "extra @mods tag");
+  }
+
+  @Test
+  public void testBadMods1() {
+    parseFileOverview("@mods {} */", "malformed @mods tag");
+  }
+
+  @Test
+  public void testBadMods2() {
+    parseFileOverview("@mods { */", "malformed @mods tag");
+  }
+
+  @Test
+  public void testBadMods3() {
+    parseFileOverview("@mods } */", "malformed @mods tag");
+  }
+
+  @Test
+  public void testBadMods4() {
+    parseFileOverview("@mods ns.Foo */", "malformed @mods tag");
+  }
+
+  @Test
+  public void testBadMods5() {
+    parseFileOverview("@mods {ns.Foo */", "malformed @mods tag");
+  }
+
+  @Test
+  public void testBadMods6() {
+    parseFileOverview("@mods ns.Foo} */", "malformed @mods tag");
+  }
+
   @Test
   public void testModifies1() {
     JSDocInfo info = parse("@modifies {this} */");
@@ -5161,7 +5214,6 @@ public void testAllowlistedAnnotations() {
             + "* @member \n"
             + "* @memberOf \n"
             + "* @modName \n"
-            + "* @mods \n"
             + "* @name \n"
             + "* @namespace \n"
             + "* @ngInject \n"