Skip to content

Commit

Permalink
8285368: Overhaul doc-comment inheritance
Browse files Browse the repository at this point in the history
6376959: Algorithm for Inheriting Method Comments seems to go not as documented
6934301: Support directed inheriting of class comments with @inheritdoc

Reviewed-by: jjg, rriggs, aivanov, smarks, martin
  • Loading branch information
pavelrappo committed Jun 15, 2023
1 parent 3eeb681 commit 3e0bbd2
Show file tree
Hide file tree
Showing 32 changed files with 1,736 additions and 134 deletions.
2 changes: 2 additions & 0 deletions src/java.base/share/classes/java/util/TreeMap.java
Original file line number Diff line number Diff line change
Expand Up @@ -1195,6 +1195,8 @@ public Collection<V> values() {
* {@code Set.remove}, {@code removeAll}, {@code retainAll} and
* {@code clear} operations. It does not support the
* {@code add} or {@code addAll} operations.
*
* @return {@inheritDoc SortedMap}
*/
public Set<Map.Entry<K,V>> entrySet() {
EntrySet es = entrySet;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1531,7 +1531,7 @@ private void readObject(java.io.ObjectInputStream s)
// ConcurrentMap methods

/**
* {@inheritDoc}
* {@inheritDoc ConcurrentMap}
*
* @return the previous value associated with the specified key,
* or {@code null} if there was no mapping for the key
Expand All @@ -1542,9 +1542,10 @@ public V putIfAbsent(K key, V value) {
}

/**
* {@inheritDoc}
* {@inheritDoc ConcurrentMap}
*
* @throws NullPointerException if the specified key is null
* @return {@inheritDoc ConcurrentMap}
*/
public boolean remove(Object key, Object value) {
if (key == null)
Expand All @@ -1553,9 +1554,10 @@ public boolean remove(Object key, Object value) {
}

/**
* {@inheritDoc}
* {@inheritDoc ConcurrentMap}
*
* @throws NullPointerException if any of the arguments are null
* @return {@inheritDoc ConcurrentMap}
*/
public boolean replace(K key, V oldValue, V newValue) {
if (key == null || oldValue == null || newValue == null)
Expand All @@ -1564,7 +1566,7 @@ public boolean replace(K key, V oldValue, V newValue) {
}

/**
* {@inheritDoc}
* {@inheritDoc ConcurrentMap}
*
* @return the previous value associated with the specified key,
* or {@code null} if there was no mapping for the key
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1773,7 +1773,7 @@ public boolean equals(Object o) {
/* ------ ConcurrentMap API methods ------ */

/**
* {@inheritDoc}
* {@inheritDoc ConcurrentMap}
*
* @return the previous value associated with the specified key,
* or {@code null} if there was no mapping for the key
Expand All @@ -1788,11 +1788,12 @@ public V putIfAbsent(K key, V value) {
}

/**
* {@inheritDoc}
* {@inheritDoc ConcurrentMap}
*
* @throws ClassCastException if the specified key cannot be compared
* with the keys currently in the map
* @throws NullPointerException if the specified key is null
* @return {@inheritDoc ConcurrentMap}
*/
public boolean remove(Object key, Object value) {
if (key == null)
Expand All @@ -1801,11 +1802,12 @@ public boolean remove(Object key, Object value) {
}

/**
* {@inheritDoc}
* {@inheritDoc ConcurrentMap}
*
* @throws ClassCastException if the specified key cannot be compared
* with the keys currently in the map
* @throws NullPointerException if any of the arguments are null
* @return {@inheritDoc ConcurrentMap}
*/
public boolean replace(K key, V oldValue, V newValue) {
if (key == null || oldValue == null || newValue == null)
Expand All @@ -1824,7 +1826,7 @@ public boolean replace(K key, V oldValue, V newValue) {
}

/**
* {@inheritDoc}
* {@inheritDoc ConcurrentMap}
*
* @return the previous value associated with the specified key,
* or {@code null} if there was no mapping for the key
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -628,7 +628,9 @@ public boolean add(E e) {
}

/**
* {@inheritDoc BlockingDeque}
* @throws NullPointerException if the specified element is null
* @return {@inheritDoc BlockingDeque}
*/
public boolean offer(E e) {
return offerLast(e);
Expand Down Expand Up @@ -665,6 +667,10 @@ public E remove() {
return removeFirst();
}

/**
* {@inheritDoc BlockingDeque}
* @return {@inheritDoc BlockingDeque}
*/
public E poll() {
return pollFirst();
}
Expand All @@ -691,6 +697,10 @@ public E element() {
return getFirst();
}

/**
* {@inheritDoc BlockingDeque}
* @return {@inheritDoc BlockingDeque}
*/
public E peek() {
return peekFirst();
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -240,6 +240,11 @@ public void close() throws IOException {
StreamCloser.removeFromQueue(closeAction);
}

/**
* {@inheritDoc ImageOutputStream}
* @param pos {@inheritDoc ImageOutputStream}
* @throws IOException {@inheritDoc ImageOutputStream}
*/
public void flushBefore(long pos) throws IOException {
long oFlushedPos = flushedPos;
super.flushBefore(pos); // this will call checkClosed() for us
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -184,6 +184,11 @@ public void close() throws IOException {
stream = null;
}

/**
* {@inheritDoc ImageOutputStream}
* @param pos {@inheritDoc ImageOutputStream}
* @throws IOException {@inheritDoc ImageOutputStream}
*/
public void flushBefore(long pos) throws IOException {
long oFlushedPos = flushedPos;
super.flushBefore(pos); // this will call checkClosed() for us
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -248,6 +248,10 @@ public class MouseInputHandler extends MouseInputAdapter
*/
public MouseInputHandler() {}

/**
* {@inheritDoc java.awt.event.MouseListener}
* @param e {@inheritDoc java.awt.event.MouseListener}
*/
public void mouseReleased(MouseEvent e) {
_x = 0;
_y = 0;
Expand All @@ -263,6 +267,10 @@ public void mouseReleased(MouseEvent e) {

}

/**
* {@inheritDoc java.awt.event.MouseListener}
* @param e {@inheritDoc java.awt.event.MouseListener}
*/
public void mousePressed(MouseEvent e) {
Point p = SwingUtilities.convertPoint((Component)e.getSource(),
e.getX(), e.getY(), null);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -855,6 +855,10 @@ protected class BorderListener extends MouseInputAdapter implements SwingConstan
*/
protected BorderListener() {}

/**
* {@inheritDoc java.awt.event.MouseListener}
* @param e {@inheritDoc java.awt.event.MouseListener}
*/
public void mouseClicked(MouseEvent e) {
if(e.getClickCount() > 1 && e.getSource() == getNorthPane()) {
if(frame.isIconifiable() && frame.isIcon()) {
Expand Down Expand Up @@ -911,10 +915,18 @@ void finishMouseReleased() {
discardRelease = true;
}

/**
* {@inheritDoc java.awt.event.MouseListener}
* @param e {@inheritDoc java.awt.event.MouseListener}
*/
public void mouseReleased(MouseEvent e) {
finishMouseReleased();
}

/**
* {@inheritDoc java.awt.event.MouseListener}
* @param e {@inheritDoc java.awt.event.MouseListener}
*/
public void mousePressed(MouseEvent e) {
Point p = SwingUtilities.convertPoint((Component)e.getSource(),
e.getX(), e.getY(), null);
Expand Down Expand Up @@ -1300,10 +1312,18 @@ else if(ep.x > frame.getWidth() - resizeCornerSize - i.right)
updateFrameCursor();
}

/**
* {@inheritDoc java.awt.event.MouseListener}
* @param e {@inheritDoc java.awt.event.MouseListener}
*/
public void mouseEntered(MouseEvent e) {
updateFrameCursor();
}

/**
* {@inheritDoc java.awt.event.MouseListener}
* @param e {@inheritDoc java.awt.event.MouseListener}
*/
public void mouseExited(MouseEvent e) {
updateFrameCursor();
}
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2011, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2011, 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 @@ -30,8 +30,21 @@
*
* <pre>
* {&#064;inheritDoc}
* {&#064;inheritDoc supertype}
* </pre>
*
* @since 1.8
*/
public interface InheritDocTree extends InlineTagTree { }
public interface InheritDocTree extends InlineTagTree {

/**
* {@return the reference to a superclass or superinterface from which
* to inherit documentation, or {@code null} if no reference was provided}
*
* @implSpec this implementation returns {@code null}.
* @since 22
*/
default ReferenceTree getSupertype() {
return null;
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -238,6 +238,17 @@ DocCommentTree newDocCommentTree(List<? extends DocTree> fullBody,
*/
InheritDocTree newInheritDocTree();

/**
* Creates a new {@code InheritDocTree} object, to represent an {@code {@inheritDoc}} tag.
* @param supertype a superclass or superinterface reference
* @return an {@code InheritDocTree} object
* @implSpec This implementation throws {@code UnsupportedOperationException}.
* @since 22
*/
default InheritDocTree newInheritDocTree(ReferenceTree supertype) {
throw new UnsupportedOperationException();
}

/**
* Creates a new {@code LinkTree} object, to represent a {@code {@link }} tag.
* @param ref the API element being referenced
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -340,15 +340,15 @@ public R visitIndex(IndexTree node, P p) {
/**
* {@inheritDoc}
*
* @implSpec This implementation returns {@code null}.
* @implSpec This implementation scans the children in left to right order.
*
* @param node {@inheritDoc}
* @param p {@inheritDoc}
* @return the result of scanning
*/
@Override
public R visitInheritDoc(InheritDocTree node, P p) {
return null;
return scan(node.getSupertype(), p);
}

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1301,13 +1301,21 @@ public DCTree parse(int pos) throws ParseException {
}
},

// {@inheritDoc}
// {@inheritDoc class-name}
new TagParser(TagParser.Kind.INLINE, DCTree.Kind.INHERIT_DOC) {
@Override
public DCTree parse(int pos) throws ParseException {
DCReference ref = reference(ReferenceParser.Mode.MEMBER_DISALLOWED);
skipWhitespace();
if (ch == '}') {
nextChar();
return m.at(pos).newInheritDocTree();
// for backward compatibility, use the original legacy
// method if no ref is given
if (ref == null) {
return m.at(pos).newInheritDocTree();
} else {
return m.at(pos).newInheritDocTree(ref);
}
}
final int errorPos = bp;
inlineText(WhitespaceRetentionPolicy.REMOVE_ALL); // skip unexpected content
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -748,11 +748,22 @@ public java.util.List<? extends DocTree> getDescription() {
}

public static class DCInheritDoc extends DCInlineTag<DCInheritDoc> implements InheritDocTree {
public final DCReference supertype;

public DCInheritDoc(DCReference supertype) {
this.supertype = supertype;
}

@Override @DefinedBy(Api.COMPILER_TREE)
public Kind getKind() {
return Kind.INHERIT_DOC;
}

@Override
public ReferenceTree getSupertype() {
return supertype;
}

@Override @DefinedBy(Api.COMPILER_TREE)
public <R, D> R accept(DocTreeVisitor<R, D> v, D d) {
return v.visitInheritDoc(this, d);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -310,6 +310,10 @@ public Void visitInheritDoc(InheritDocTree node, Void p) {
try {
print('{');
printTagName(node);
if (node.getSupertype() != null) {
print(" ");
print(node.getSupertype());
}
print('}');
} catch (IOException e) {
throw new UncheckedIOException(e);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -311,7 +311,12 @@ public DCIndex newIndexTree(DocTree term, List<? extends DocTree> description) {

@Override @DefinedBy(Api.COMPILER_TREE)
public DCInheritDoc newInheritDocTree() {
DCInheritDoc tree = new DCInheritDoc();
return newInheritDocTree(null);
}

@Override @DefinedBy(Api.COMPILER_TREE)
public DCInheritDoc newInheritDocTree(ReferenceTree supertype) {
DCInheritDoc tree = new DCInheritDoc((DCReference) supertype);
tree.pos = pos;
return tree;
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,7 @@ doclet.Version=Version:
doclet.Factory=Factory:
doclet.UnknownTag={0} is an unknown tag.
doclet.UnknownTagLowercase={0} is an unknown tag -- same as a known tag except for case.
doclet.inheritDocBadSupertype=cannot find the overridden method
doclet.inheritDocWithinInappropriateTag=@inheritDoc cannot be used within this tag
doclet.inheritDocNoDoc=overridden methods do not document exception type {0}
doclet.throwsInheritDocUnsupported=@inheritDoc is not supported for exception-type type parameters \
Expand Down

1 comment on commit 3e0bbd2

@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.