stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8252882: Clean up jdk.javadoc and the related parts of jdk.compiler

Browse Source 
Reviewed-by: vromero
This commit is contained in:
Pavel Rappo 2020-09-14 17:21:42 +00:00
parent 68da63dcde
commit e6a493ab88
11 changed files with 82 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
src/java.compiler/share/classes/javax/tools/ForwardingFileObject.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2006, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2006, 2020, 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
@ -50,17 +50,19 @@ public class ForwardingFileObject<F extends FileObject> implements FileObject {
protected final F fileObject;
/**
* Creates a new instance of ForwardingFileObject.
* Creates a new instance of {@code ForwardingFileObject}.
* @param fileObject delegate to this file object
*/
protected ForwardingFileObject(F fileObject) {
this.fileObject = Objects.requireNonNull(fileObject);
}
@Override
public URI toUri() {
return fileObject.toUri();
}
@Override
public String getName() {
return fileObject.getName();
}
@ -70,6 +72,7 @@ public class ForwardingFileObject<F extends FileObject> implements FileObject {
* @throws UnsupportedOperationException {@inheritDoc}
* @throws IOException {@inheritDoc}
*/
@Override
public InputStream openInputStream() throws IOException {
return fileObject.openInputStream();
}
@ -79,6 +82,7 @@ public class ForwardingFileObject<F extends FileObject> implements FileObject {
* @throws UnsupportedOperationException {@inheritDoc}
* @throws IOException {@inheritDoc}
*/
@Override
public OutputStream openOutputStream() throws IOException {
return fileObject.openOutputStream();
}
@ -88,6 +92,7 @@ public class ForwardingFileObject<F extends FileObject> implements FileObject {
* @throws UnsupportedOperationException {@inheritDoc}
* @throws IOException {@inheritDoc}
*/
@Override
public Reader openReader(boolean ignoreEncodingErrors) throws IOException {
return fileObject.openReader(ignoreEncodingErrors);
}
@ -97,6 +102,7 @@ public class ForwardingFileObject<F extends FileObject> implements FileObject {
* @throws UnsupportedOperationException {@inheritDoc}
* @throws IOException {@inheritDoc}
*/
@Override
public CharSequence getCharContent(boolean ignoreEncodingErrors) throws IOException {
return fileObject.getCharContent(ignoreEncodingErrors);
}
@ -106,14 +112,17 @@ public class ForwardingFileObject<F extends FileObject> implements FileObject {
* @throws UnsupportedOperationException {@inheritDoc}
* @throws IOException {@inheritDoc}
*/
@Override
public Writer openWriter() throws IOException {
return fileObject.openWriter();
}
@Override
public long getLastModified() {
return fileObject.getLastModified();
}
@Override
public boolean delete() {
return fileObject.delete();
}

23
src/java.compiler/share/classes/javax/tools/ForwardingJavaFileManager.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -49,7 +49,7 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
protected final M fileManager;
/**
* Creates a new instance of ForwardingJavaFileManager.
* Creates a new instance of {@code ForwardingJavaFileManager}.
* @param fileManager delegate to this file manager
*/
protected ForwardingJavaFileManager(M fileManager) {
@ -60,6 +60,7 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
* @throws SecurityException {@inheritDoc}
* @throws IllegalStateException {@inheritDoc}
*/
@Override
public ClassLoader getClassLoader(Location location) {
return fileManager.getClassLoader(location);
}
@ -68,6 +69,7 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
* @throws IOException {@inheritDoc}
* @throws IllegalStateException {@inheritDoc}
*/
@Override
public Iterable<JavaFileObject> list(Location location,
String packageName,
Set<Kind> kinds,
@ -80,6 +82,7 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
/**
* @throws IllegalStateException {@inheritDoc}
*/
@Override
public String inferBinaryName(Location location, JavaFileObject file) {
return fileManager.inferBinaryName(location, file);
}
@ -87,6 +90,7 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
/**
* @throws IllegalArgumentException {@inheritDoc}
*/
@Override
public boolean isSameFile(FileObject a, FileObject b) {
return fileManager.isSameFile(a, b);
}
@ -95,14 +99,17 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
* @throws IllegalArgumentException {@inheritDoc}
* @throws IllegalStateException {@inheritDoc}
*/
@Override
public boolean handleOption(String current, Iterator<String> remaining) {
return fileManager.handleOption(current, remaining);
}
@Override
public boolean hasLocation(Location location) {
return fileManager.hasLocation(location);
}
@Override
public int isSupportedOption(String option) {
return fileManager.isSupportedOption(option);
}
@ -111,6 +118,7 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
* @throws IllegalArgumentException {@inheritDoc}
* @throws IllegalStateException {@inheritDoc}
*/
@Override
public JavaFileObject getJavaFileForInput(Location location,
String className,
Kind kind)
@ -123,6 +131,7 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
* @throws IllegalArgumentException {@inheritDoc}
* @throws IllegalStateException {@inheritDoc}
*/
@Override
public JavaFileObject getJavaFileForOutput(Location location,
String className,
Kind kind,
@ -136,6 +145,7 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
* @throws IllegalArgumentException {@inheritDoc}
* @throws IllegalStateException {@inheritDoc}
*/
@Override
public FileObject getFileForInput(Location location,
String packageName,
String relativeName)
@ -148,6 +158,7 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
* @throws IllegalArgumentException {@inheritDoc}
* @throws IllegalStateException {@inheritDoc}
*/
@Override
public FileObject getFileForOutput(Location location,
String packageName,
String relativeName,
@ -157,10 +168,12 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
return fileManager.getFileForOutput(location, packageName, relativeName, sibling);
}
@Override
public void flush() throws IOException {
fileManager.flush();
}
@Override
public void close() throws IOException {
fileManager.close();
}
@ -169,6 +182,7 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
* @since 9
* @spec JPMS
*/
@Override
public Location getLocationForModule(Location location, String moduleName) throws IOException {
return fileManager.getLocationForModule(location, moduleName);
}
@ -177,6 +191,7 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
* @since 9
* @spec JPMS
*/
@Override
public Location getLocationForModule(Location location, JavaFileObject fo) throws IOException {
return fileManager.getLocationForModule(location, fo);
}
@ -185,6 +200,7 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
* @since 9
* @spec JPMS
*/
@Override
public <S> ServiceLoader<S> getServiceLoader(Location location, Class<S> service) throws IOException {
return fileManager.getServiceLoader(location, service);
}
@ -193,6 +209,7 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
* @since 9
* @spec JPMS
*/
@Override
public String inferModuleName(Location location) throws IOException {
return fileManager.inferModuleName(location);
}
@ -201,6 +218,7 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
* @since 9
* @spec JPMS
*/
@Override
public Iterable<Set<Location>> listLocationsForModules(Location location) throws IOException {
return fileManager.listLocationsForModules(location);
}
@ -208,6 +226,7 @@ public class ForwardingJavaFileManager<M extends JavaFileManager> implements Jav
/**
* @since 9
*/
@Override
public boolean contains(Location location, FileObject fo) throws IOException {
return fileManager.contains(location, fo);
}

8
src/java.compiler/share/classes/javax/tools/ForwardingJavaFileObject.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -43,23 +43,27 @@ public class ForwardingJavaFileObject<F extends JavaFileObject>
{
/**
* Creates a new instance of ForwardingJavaFileObject.
* Creates a new instance of {@code ForwardingJavaFileObject}.
* @param fileObject delegate to this file object
*/
protected ForwardingJavaFileObject(F fileObject) {
super(fileObject);
}
@Override
public Kind getKind() {
return fileObject.getKind();
}
@Override
public boolean isNameCompatible(String simpleName, Kind kind) {
return fileObject.isNameCompatible(simpleName, kind);
}
@Override
public NestingKind getNestingKind() { return fileObject.getNestingKind(); }
@Override
public Modifier getAccessLevel() { return fileObject.getAccessLevel(); }
}

14
src/java.compiler/share/classes/javax/tools/JavaFileObject.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2014, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -63,8 +63,7 @@ public interface JavaFileObject extends FileObject {
CLASS(".class"),
/**
* HTML files. For example, regular files ending with {@code
* .html}.
* HTML files. For example, regular files ending with {@code .html}.
*/
HTML(".html"),
@ -78,7 +77,7 @@ public interface JavaFileObject extends FileObject {
* empty string ({@code ""}) is used.
*/
public final String extension;
private Kind(String extension) {
Kind(String extension) {
this.extension = Objects.requireNonNull(extension);
}
}
@ -94,12 +93,11 @@ public interface JavaFileObject extends FileObject {
* Checks if this file object is compatible with the specified
* simple name and kind. A simple name is a single identifier
* (not qualified) as defined in
* <cite>The Java Language Specification</cite>,
* section 6.2 "Names and Identifiers".
* <cite>The Java Language Specification</cite>, section {@jls 6.2}.
*
* @param simpleName a simple name of a class
* @param kind a kind
* @return {@code true} if this file object is compatible; false
* @return {@code true} if this file object is compatible; {@code false}
* otherwise
*/
boolean isNameCompatible(String simpleName, Kind kind);
@ -119,7 +117,7 @@ public interface JavaFileObject extends FileObject {
/**
* Provides a hint about the access level of the class represented
* by this file object. If the access level is not known or if
* by this file object. If the access level is not known or
* this file object does not represent a class file this method
* returns {@code null}.
*

3
src/java.compiler/share/classes/javax/tools/SimpleJavaFileObject.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -31,7 +31,6 @@ import java.nio.CharBuffer;
import java.util.Objects;
import javax.lang.model.element.Modifier;
import javax.lang.model.element.NestingKind;
import javax.tools.JavaFileObject.Kind;
/**
* Provides simple implementations for most methods in JavaFileObject.

18
src/java.compiler/share/classes/javax/tools/StandardJavaFileManager.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2006, 2018, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2006, 2020, 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
@ -35,7 +35,7 @@ import java.util.Iterator;
import java.util.List;
/**
* File manager based on {@linkplain File java.io.File} and {@linkplain Path java.nio.file.Path}.
* File manager based on {@link File java.io.File} and {@link Path java.nio.file.Path}.
*
* A common way to obtain an instance of this class is using
* {@linkplain JavaCompiler#getStandardFileManager getStandardFileManager}, for example:
@ -363,7 +363,7 @@ public interface StandardJavaFileManager extends JavaFileManager {
*
* All such module-specific associations will be cancelled if a
* new search path is associated with the location by calling
* {@linkplain #setLocation setLocation } or
* {@linkplain #setLocation setLocation} or
* {@linkplain #setLocationFromPaths setLocationFromPaths}.
*
* @throws IllegalStateException if the location is not a module-oriented
@ -377,8 +377,8 @@ public interface StandardJavaFileManager extends JavaFileManager {
* @param moduleName the name of the module
* @param paths the search path to associate with the location and module.
*
* @see setLocation
* @see setLocationFromPaths
* @see #setLocation
* @see #setLocationFromPaths
*
* @since 9
*/
@ -480,8 +480,8 @@ public interface StandardJavaFileManager extends JavaFileManager {
private static Iterable<Path> asPaths(final Iterable<? extends File> files) {
return () -> new Iterator<Path>() {
Iterator<? extends File> iter = files.iterator();
return () -> new Iterator<>() {
final Iterator<? extends File> iter = files.iterator();
@Override
public boolean hasNext() {
@ -496,8 +496,8 @@ public interface StandardJavaFileManager extends JavaFileManager {
}
private static Iterable<File> asFiles(final Iterable<? extends Path> paths) {
return () -> new Iterator<File>() {
Iterator<? extends Path> iter = paths.iterator();
return () -> new Iterator<>() {
final Iterator<? extends Path> iter = paths.iterator();
@Override
public boolean hasNext() {

18
src/java.compiler/share/classes/javax/tools/package-info.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -32,25 +32,25 @@
* but there is no requirement to provide any tools implementing them.
*
* <p>Unless explicitly allowed, all methods in this package might
* throw a {@linkplain java.lang.NullPointerException} if given a
* throw a {@link java.lang.NullPointerException} if given a
* {@code null} argument or if given a
* {@linkplain java.lang.Iterable list or collection} containing
* {@code null} elements. Similarly, no method may return
* {@code null} unless explicitly allowed.
*
* <p>This package is the home of the Java programming language compiler framework. This
* framework allows clients of the framework to locate and run
* <p>This package is the home of the Java programming language compiler framework.
* This framework allows clients of the framework to locate and run
* compilers from programs. The framework also provides Service
* Provider Interfaces (SPI) for structured access to diagnostics
* ({@linkplain javax.tools.DiagnosticListener}) as well as a file
* abstraction for overriding file access ({@linkplain
* javax.tools.JavaFileManager} and {@linkplain
* javax.tools.JavaFileObject}). See {@linkplain
* ({@link javax.tools.DiagnosticListener}) as well as a file
* abstraction for overriding file access ({@link
* javax.tools.JavaFileManager} and {@link
* javax.tools.JavaFileObject}). See {@link
* javax.tools.JavaCompiler} for more details on using the SPI.
*
* <p>There is no requirement for a compiler at runtime. However, if
* a default compiler is provided, it can be located using the
* {@linkplain javax.tools.ToolProvider}, for example:
* {@link javax.tools.ToolProvider}, for example:
*
* <p>{@code JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();}
*

4
src/jdk.compiler/share/classes/com/sun/source/doctree/DocRootTree.java
View File

@ -26,10 +26,10 @@
package com.sun.source.doctree;
/**
* A tree node for an {@code @docroot} inline tag.
* A tree node for an {@code @docRoot} inline tag.
*
* <pre>
* {&#064;docroot}
* {&#064;docRoot}
* </pre>
*
* @since 1.8

2
src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java
View File

@ -137,7 +137,7 @@ public interface DocTreeFactory {
List<? extends DocTree> preamble,
List<? extends DocTree> postamble);
/**
* Creates a new {@code DocRootTree} object, to represent an {@code {@docroot}} tag.
* Creates a new {@code DocRootTree} object, to represent an {@code {@docRoot}} tag.
* @return a {@code DocRootTree} object
*/
DocRootTree newDocRootTree();

22
src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java
View File

@ -248,7 +248,7 @@ public class DocCommentParser {
*/
protected List<DCTree> blockTags() {
ListBuffer<DCTree> tags = new ListBuffer<>();
while (ch == '@')
while (bp < buflen && ch == '@')
tags.add(blockTag());
return tags.toList();
}
@ -354,7 +354,7 @@ public class DocCommentParser {
* Matching pairs of { } are skipped; the text is terminated by the first
* unmatched }. It is an error if the beginning of the next tag is detected.
*/
private DCTree inlineText(WhitespaceRetentionPolicy whitespacePolicy) throws ParseException {
private DCText inlineText(WhitespaceRetentionPolicy whitespacePolicy) throws ParseException {
switch (whitespacePolicy) {
case REMOVE_ALL:
skipWhitespace();
@ -663,14 +663,14 @@ public class DocCommentParser {
nextChar();
if (isDecimalDigit(ch)) {
nextChar();
while (isDecimalDigit(ch))
while (bp < buflen && isDecimalDigit(ch))
nextChar();
name = names.fromChars(buf, namep, bp - namep);
} else if (ch == 'x' || ch == 'X') {
nextChar();
if (isHexDigit(ch)) {
nextChar();
while (isHexDigit(ch))
while (bp < buflen && isHexDigit(ch))
nextChar();
name = names.fromChars(buf, namep, bp - namep);
}
@ -843,7 +843,7 @@ public class DocCommentParser {
nextChar();
while (bp < buflen) {
int dash = 0;
while (ch == '-') {
while (bp < buflen && ch == '-') {
dash++;
nextChar();
}
@ -890,7 +890,7 @@ public class DocCommentParser {
skipWhitespace();
loop:
while (isIdentifierStart(ch)) {
while (bp < buflen && isIdentifierStart(ch)) {
int namePos = bp;
Name name = readAttributeName();
skipWhitespace();
@ -1057,7 +1057,7 @@ public class DocCommentParser {
}
protected void skipWhitespace() {
while (isWhitespace(ch)) {
while (bp < buflen && isWhitespace(ch)) {
nextChar();
}
}
@ -1118,9 +1118,9 @@ public class DocCommentParser {
new TagParser(TagParser.Kind.INLINE, DCTree.Kind.CODE, true) {
@Override
public DCTree parse(int pos) throws ParseException {
DCTree text = inlineText(WhitespaceRetentionPolicy.REMOVE_FIRST_SPACE);
DCText text = inlineText(WhitespaceRetentionPolicy.REMOVE_FIRST_SPACE);
nextChar();
return m.at(pos).newCodeTree((DCText) text);
return m.at(pos).newCodeTree(text);
}
},
@ -1228,9 +1228,9 @@ public class DocCommentParser {
new TagParser(TagParser.Kind.INLINE, DCTree.Kind.LITERAL, true) {
@Override
public DCTree parse(int pos) throws ParseException {
DCTree text = inlineText(WhitespaceRetentionPolicy.REMOVE_FIRST_SPACE);
DCText text = inlineText(WhitespaceRetentionPolicy.REMOVE_FIRST_SPACE);
nextChar();
return m.at(pos).newLiteralTree((DCText) text);
return m.at(pos).newLiteralTree(text);
}
},

14
src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java
View File

@ -161,14 +161,14 @@ public class DocTreeMaker implements DocTreeFactory {
}
@Override @DefinedBy(Api.COMPILER_TREE)
public DCAttribute newAttributeTree(javax.lang.model.element.Name name, ValueKind vkind, java.util.List<? extends DocTree> value) {
public DCAttribute newAttributeTree(Name name, ValueKind vkind, List<? extends DocTree> value) {
DCAttribute tree = new DCAttribute(name, vkind, cast(value));
tree.pos = pos;
return tree;
}
@Override @DefinedBy(Api.COMPILER_TREE)
public DCAuthor newAuthorTree(java.util.List<? extends DocTree> name) {
public DCAuthor newAuthorTree(List<? extends DocTree> name) {
DCAuthor tree = new DCAuthor(cast(name));
tree.pos = pos;
return tree;
@ -197,11 +197,7 @@ public class DocTreeMaker implements DocTreeFactory {
@Override @DefinedBy(Api.COMPILER_TREE)
public DCDocComment newDocCommentTree(List<? extends DocTree> fullBody, List<? extends DocTree> tags) {
Pair<List<DCTree>, List<DCTree>> pair = splitBody(fullBody);
List<DCTree> preamble = Collections.emptyList();
List<DCTree> postamble = Collections.emptyList();
return newDocCommentTree(fullBody, tags, preamble, postamble);
return newDocCommentTree(fullBody, tags, Collections.emptyList(), Collections.emptyList());
}
public DCDocComment newDocCommentTree(Comment comment,
@ -503,7 +499,7 @@ public class DocTreeMaker implements DocTreeFactory {
}
@Override @DefinedBy(Api.COMPILER_TREE)
public java.util.List<DocTree> getFirstSentence(java.util.List<? extends DocTree> list) {
public List<DocTree> getFirstSentence(List<? extends DocTree> list) {
Pair<List<DCTree>, List<DCTree>> pair = splitBody(list);
return new ArrayList<>(pair.fst);
}
@ -693,7 +689,7 @@ public class DocTreeMaker implements DocTreeFactory {
return -1; // indeterminate at this time
}
private boolean isSentenceBreak(javax.lang.model.element.Name tagName) {
private boolean isSentenceBreak(Name tagName) {
return sentenceBreakTags.contains(get(tagName));
}