Bug 104245

Summary: AST.newCompilationUnit javadoc error
Product: [Eclipse Project] JDT Reporter: Greg Dennis <gdennis>
Component: CoreAssignee: Jim des Rivieres <jeem>
Status: VERIFIED FIXED QA Contact:
Severity: minor    
Priority: P3    
Version: 3.1   
Target Milestone: 3.2 M1   
Hardware: All   
OS: All   
Whiteboard:

Description Greg Dennis CLA 2005-07-18 14:12:49 EDT 
The Javadoc for AST.newCompilationUnit contains the following second paragraph:
"Note that the new compilation unit is not automatically made the root node of
this AST. This must be done explicitly by calling setRoot." But there is no
method setRoot, at least no such public method.

In fact, the abstract syntax "tree" is actually a forest, because there can be
multiple nodes without parents. And calling the getRoot method on a particular
node will actually return the root of the tree in the forest to which that node
belongs. To make a node the only root of the AST, one must only make every other
node children or descendents of it.

Two suggested changes: (1) remove the second paragraph from newCompilationUnit
javadoc and (2) include some discussion of what the "root" of an AST is in the
Javadoc for the AST type.
Comment 1 Jim des Rivieres CLA 2005-07-19 08:49:29 EDT 
Good suggestions, both. I've deleted the extraneous passage that 
mentions "setRoot()" (a leftover from the early design days).

Added the following para to AST class spec:

 * <p>
 * There can be any number of AST nodes owned by a single AST instance that are
 * unparented. Each of these nodes is the root of a separate little tree of 
nodes.
 * The method <code>ASTNode.getRoot()</code> navigates from any node to the 
root
 * of the tree that it is contained in. Ordinarily, an AST instance has one 
main
 * tree (rooted at a <code>CompilationUnit</code>), with newly-created nodes 
appearing
 * as additional roots until they are parented somewhere under the main tree.
 * One can navigate from any node to its AST instance, but not conversely.
 * </p>

Release to HEAD (3.2) stream. Updated build nodes.
Comment 2 Olivier Thomann CLA 2005-08-09 10:35:40 EDT 
Verified in 3.2M1 (I20050808-2000)