8267633: Clarify documentation of (Doc)TreeScanner

Reviewed-by: jjg

src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2021, 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
@@ -40,13 +40,13 @@
  * <ul>
  * <li>If the node being visited has no children, the result will be {@code null}.
  * <li>If the node being visited has one child, the result will be the
- * result of calling {@code scan} on that child. The child may be a simple node
+ * result of calling {@code scan} with that child. The child may be a simple node
  * or itself a list of nodes.
- * <li> If the node being visited has more than one child, the result will
- * be determined by calling {@code scan} each child in turn, and then combining the
+ * <li>If the node being visited has more than one child, the result will
+ * be determined by calling {@code scan} with each child in turn, and then combining the
  * result of each scan after the first with the cumulative result
  * so far, as determined by the {@link #reduce} method. Each child may be either
- * a simple node of a list of nodes. The default behavior of the {@code reduce}
+ * a simple node or a list of nodes. The default behavior of the {@code reduce}
  * method is such that the result of the visitXYZ method will be the result of
  * the last child scanned.
  * </ul>

src/jdk.compiler/share/classes/com/sun/source/util/TreePath.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2006, 2021, 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
@@ -33,7 +33,7 @@
 
 /**
  * A path of tree nodes, typically used to represent the sequence of ancestor
- * nodes of a tree node up to the top level CompilationUnitTree node.
+ * nodes of a tree node up to the top-level {@code CompilationUnitTree} node.
  *
  * @author Jonathan Gibbons
  * @since 1.6

src/jdk.compiler/share/classes/com/sun/source/util/TreeScanner.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2021, 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
@@ -39,13 +39,13 @@
  * <ul>
  * <li>If the node being visited has no children, the result will be {@code null}.
  * <li>If the node being visited has one child, the result will be the
- * result of calling {@code scan} on that child. The child may be a simple node
+ * result of calling {@code scan} with that child. The child may be a simple node
  * or itself a list of nodes.
- * <li> If the node being visited has more than one child, the result will
- * be determined by calling {@code scan} each child in turn, and then combining the
+ * <li>If the node being visited has more than one child, the result will
+ * be determined by calling {@code scan} with each child in turn, and then combining the
  * result of each scan after the first with the cumulative result
  * so far, as determined by the {@link #reduce} method. Each child may be either
- * a simple node of a list of nodes. The default behavior of the {@code reduce}
+ * a simple node or a list of nodes. The default behavior of the {@code reduce}
  * method is such that the result of the visitXYZ method will be the result of
  * the last child scanned.
  * </ul>