Skip to content

Commit

Permalink
8320234: Merge doclint.Env.AccessKind with tool.AccessKind
Browse files Browse the repository at this point in the history
Reviewed-by: jjg
  • Loading branch information
pavelrappo committed Nov 20, 2023
1 parent d6d7bdc commit 3aefd1c
Show file tree
Hide file tree
Showing 7 changed files with 132 additions and 189 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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>
}
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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) {
Expand Down
56 changes: 12 additions & 44 deletions src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Env.java
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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;

Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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;
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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) {
Expand All @@ -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()));
Expand All @@ -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";
Expand Down
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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;
}
}

1 comment on commit 3aefd1c

@openjdk-notifier
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.