8320234: Merge doclint.Env.AccessKind with tool.AccessKind

Reviewed-by: jjg

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseConfiguration.java

@@ -73,7 +73,7 @@
 import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberCache;
 import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable;
 import jdk.javadoc.internal.doclint.DocLint;
-import jdk.javadoc.internal.doclint.Env;
+import jdk.javadoc.internal.tool.AccessLevel;
 
 /**
  * Configure the output based on the options. Doclets should subclass
@@ -654,10 +654,10 @@ public boolean isDocLintSyntaxGroupEnabled() {
 
     private boolean isDocLintGroupEnabled(jdk.javadoc.internal.doclint.Messages.Group group) {
         // Use AccessKind.PUBLIC as a stand-in, since it is not common to
-        // set DocLint options per access kind (as is common with javac.)
-        // A more sophisticated solution might be to derive the access kind from the
+        // set DocLint options per access level (as is common with javac.)
+        // A more sophisticated solution might be to derive the access level from the
         // element owning the comment, and its enclosing elements.
-        return doclint != null && doclint.isGroupEnabled(group, Env.AccessKind.PUBLIC);
+        return doclint != null && doclint.isGroupEnabled(group, AccessLevel.PUBLIC);
     }
     //</editor-fold>
 }

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/DocLint.java

@@ -64,6 +64,7 @@
 import com.sun.tools.javac.util.DefinedBy;
 import com.sun.tools.javac.util.DefinedBy.Api;
 import com.sun.tools.javac.util.StringUtils.DamerauLevenshteinDistance;
+import jdk.javadoc.internal.tool.AccessLevel;
 
 /**
  * Multi-function entry point for the doc check utility.
@@ -410,8 +411,8 @@ public boolean isValidOption(String opt) {
         return false;
     }
 
-    public boolean isGroupEnabled(Messages.Group group, Env.AccessKind accessKind) {
-        return env.messages.isEnabled(group, accessKind);
+    public boolean isGroupEnabled(Messages.Group group, AccessLevel accessLevel) {
+        return env.messages.isEnabled(group, accessLevel);
     }
 
     private String localize(String code, Object... args) {

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Env.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -62,38 +62,13 @@
 import com.sun.tools.javac.tree.JCTree;
 import com.sun.tools.javac.util.MatchingUtils;
 import com.sun.tools.javac.util.StringUtils;
+import jdk.javadoc.internal.tool.AccessLevel;
 
 /**
  * Utility container for current execution environment,
  * providing the current declaration and its doc comment.
  */
 public class Env {
-    /**
-     * Access kinds for declarations.
-     */
-    public enum AccessKind {
-        PRIVATE,
-        PACKAGE,
-        PROTECTED,
-        PUBLIC;
-
-        static boolean accepts(String opt) {
-            for (AccessKind g: values())
-                if (opt.equals(StringUtils.toLowerCase(g.name()))) return true;
-            return false;
-        }
-
-        static AccessKind of(Set<Modifier> mods) {
-            if (mods.contains(Modifier.PUBLIC))
-                return AccessKind.PUBLIC;
-            else if (mods.contains(Modifier.PROTECTED))
-                return AccessKind.PROTECTED;
-            else if (mods.contains(Modifier.PRIVATE))
-                return AccessKind.PRIVATE;
-            else
-                return AccessKind.PACKAGE;
-        }
-    }
 
     /** Message handler. */
     final Messages messages;
@@ -136,12 +111,12 @@ else if (mods.contains(Modifier.PRIVATE))
     /** The comment current being analyzed. */
     DocCommentTree currDocComment;
     /**
-     * The access kind of the declaration containing the comment currently being analyzed.
-     * This is the minimum (most restrictive) access kind of the declaration itself
+     * The access level of the declaration containing the comment currently being analyzed.
+     * This is the most limiting access level of the declaration itself
      * and that of its containers. For example, a public method in a private class is
      * noted as private.
      */
-    AccessKind currAccess;
+    AccessLevel currAccess;
     /** The set of methods, if any, that the current declaration overrides. */
     Set<? extends ExecutableElement> currOverriddenMethods;
 
@@ -219,18 +194,18 @@ void setCurrent(TreePath path, DocCommentTree comment) {
         currElement = trees.getElement(currPath);
         currOverriddenMethods = ((JavacTypes) types).getOverriddenMethods(currElement);
 
-        AccessKind ak = AccessKind.PUBLIC;
+        // It's convenient to use AccessLevel to model effects that nesting has
+        // on access. While very similar, those are not the same concept.
+        var mostLimitingSoFar = AccessLevel.PUBLIC;
         for (TreePath p = path; p != null; p = p.getParentPath()) {
             Element e = trees.getElement(p);
             if (e != null && e.getKind() != ElementKind.PACKAGE && e.getKind() != ElementKind.MODULE) {
-                ak = min(ak, AccessKind.of(e.getModifiers()));
+                var level = AccessLevel.of(e.getModifiers());
+                mostLimitingSoFar = mostLimitingSoFar.compareTo(level) <= 0
+                        ? mostLimitingSoFar : level;
             }
         }
-        currAccess = ak;
-    }
-
-    AccessKind getAccessKind() {
-        return currAccess;
+        currAccess = mostLimitingSoFar;
     }
 
     long getPos(TreePath p) {
@@ -359,11 +334,4 @@ private List<String> getSuppressWarningsValue(Element e) {
         }
         return List.of();
     }
-
-
-    private <T extends Comparable<T>> T min(T item1, T item2) {
-        return (item1 == null) ? item2
-                : (item2 == null) ? item1
-                : item1.compareTo(item2) <= 0 ? item1 : item2;
-    }
 }

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Messages.java

@@ -43,7 +43,7 @@
 import com.sun.source.tree.Tree;
 import com.sun.tools.javac.api.JavacTrees;
 import com.sun.tools.javac.util.StringUtils;
-import jdk.javadoc.internal.doclint.Env.AccessKind;
+import jdk.javadoc.internal.tool.AccessLevel;
 
 /**
  * Message reporting for DocLint.
@@ -109,8 +109,8 @@ void setStatsEnabled(boolean b) {
         stats.setEnabled(b);
     }
 
-    boolean isEnabled(Group group, Env.AccessKind ak) {
-        return options.isEnabled(group, ak);
+    boolean isEnabled(Group group, AccessLevel al) {
+        return options.isEnabled(group, al);
     }
 
     void reportStats(PrintWriter out) {
@@ -176,7 +176,7 @@ String localize(String code, Object... args) {
      * Handler for (sub)options specific to message handling.
      */
     static class Options {
-        Map<String, Env.AccessKind> map = new HashMap<>();
+        private final Map<String, AccessLevel> map = new HashMap<>();
         private final Stats stats;
 
         static boolean isValidOptions(String opts) {
@@ -195,35 +195,40 @@ private static boolean isValidOption(String opt) {
             int sep = opt.indexOf("/");
             String grp = opt.substring(begin, (sep != -1) ? sep : opt.length());
             return ((begin == 0 && grp.equals("all")) || Group.accepts(grp))
-                    && ((sep == -1) || AccessKind.accepts(opt.substring(sep + 1)));
+                    && ((sep == -1) || accepts(opt.substring(sep + 1)));
+        }
+
+        static boolean accepts(String opt) {
+            for (var level: AccessLevel.values())
+                if (opt.equals(StringUtils.toLowerCase(level.name()))) return true;
+            return false;
         }
 
         Options(Stats stats) {
             this.stats = stats;
         }
 
         /** Determine if a message group is enabled for a particular access level. */
-        boolean isEnabled(Group g, Env.AccessKind access) {
+        boolean isEnabled(Group g, AccessLevel access) {
             if (map.isEmpty())
-                map.put("all", Env.AccessKind.PROTECTED);
+                map.put(ALL, AccessLevel.PROTECTED);
 
-            Env.AccessKind ak = map.get(g.optName());
-            if (ak != null && access.compareTo(ak) >= 0)
+            AccessLevel al = map.get(g.optName());
+            if (al != null && access.compareTo(al) >= 0)
                 return true;
 
-            ak = map.get(ALL);
-            if (ak != null && access.compareTo(ak) >= 0) {
-                ak = map.get(g.notOptName());
-                if (ak == null || access.compareTo(ak) > 0) // note >, not >=
-                    return true;
+            al = map.get(ALL);
+            if (al != null && access.compareTo(al) >= 0) {
+                al = map.get(g.notOptName());
+                return al == null || access.compareTo(al) > 0; // note >, not >=
             }
 
             return false;
         }
 
         void setOptions(String opts) {
             if (opts == null)
-                setOption(ALL, Env.AccessKind.PRIVATE);
+                setOption(ALL, AccessLevel.PRIVATE);
             else {
                 for (String opt: opts.split(","))
                     setOption(StringUtils.toLowerCase(opt.trim()));
@@ -238,16 +243,16 @@ private void setOption(String arg) throws IllegalArgumentException {
 
             int sep = arg.indexOf("/");
             if (sep > 0) {
-                Env.AccessKind ak = Env.AccessKind.valueOf(StringUtils.toUpperCase(arg.substring(sep + 1)));
-                setOption(arg.substring(0, sep), ak);
+                var al = AccessLevel.valueOf(StringUtils.toUpperCase(arg.substring(sep + 1)));
+                setOption(arg.substring(0, sep), al);
             } else {
                 setOption(arg, null);
             }
         }
 
-        private void setOption(String opt, Env.AccessKind ak) {
-            map.put(opt, (ak != null) ? ak
-                    : opt.startsWith("-") ? Env.AccessKind.PUBLIC : Env.AccessKind.PRIVATE);
+        private void setOption(String opt, AccessLevel al) {
+            map.put(opt, (al != null) ? al
+                    : opt.startsWith("-") ? AccessLevel.PUBLIC : AccessLevel.PRIVATE);
         }
 
         private static final String ALL = "all";

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/AccessKind.java → src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/AccessLevel.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2016, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2016, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -25,16 +25,40 @@
 
 package jdk.javadoc.internal.tool;
 
+import java.util.Set;
+import javax.lang.model.element.Modifier;
+
 /**
- * The access value kinds.
+ * The access levels.
+ *
+ * These constants are ordered by their access limiting power. The bigger the
+ * {@link #ordinal() ordinal} of a constant, the more limiting power that
+ * constant has.
+ *
+ * That has a few useful implications. For example, the levels can be compared
+ * by {@link #compareTo}. It also means that {@code AccessLevel.values()[0]} and
+ * {@code AccessLevel.values()[values.length() - 1] and the constants with the
+ * smallest and the biggest limiting powers respectively.
  */
-public enum AccessKind {
-    /** Limits access to public entities */
-    PUBLIC,
+public enum AccessLevel implements Comparable<AccessLevel> {
+
+    /** Does not limit access */
+    PRIVATE,
+    /** Limits access to entities that are public, protected, or declared with package access */
+    PACKAGE,
     /** Limits access to public and protected entities */
     PROTECTED,
-    /** Limits access to public, protected and package private entities */
-    PACKAGE,
-    /** No limits */
-    PRIVATE;
+    /** Limits access to public entities */
+    PUBLIC;
+
+    public static AccessLevel of(Set<Modifier> mods) {
+        if (mods.contains(Modifier.PUBLIC))
+            return AccessLevel.PUBLIC;
+        else if (mods.contains(Modifier.PROTECTED))
+            return AccessLevel.PROTECTED;
+        else if (mods.contains(Modifier.PRIVATE))
+            return AccessLevel.PRIVATE;
+        else
+            return AccessLevel.PACKAGE;
+    }
 }