Bug 293711

Summary: Clarify ICompilationUnit#getOwner() javadoc
Product: [Eclipse Project] JDT Reporter: Min Idzelis <min123>
Component: CoreAssignee: Olivier Thomann <Olivier_Thomann>
Status: VERIFIED FIXED QA Contact:
Severity: normal    
Priority: P3 CC: amj87.iitr, daniel_megert, Olivier_Thomann, srikanth_sankaran
Version: 3.6   
Target Milestone: 3.6 M4   
Hardware: PC   
OS: Windows XP   
Whiteboard:
Attachments:
Description Flags
Proposed fix
none
Proposed fix none

Description Min Idzelis CLA 2009-10-29 13:57:53 EDT 
User-Agent:       Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9.1.3) Gecko/20090824 Firefox/3.5.3
Build Identifier: 

It is worth clarifying the javadoc for ICompilationUnit? This is what it says now:

WorkingCopyOwner org.eclipse.jdt.core.ICompilationUnit.getOwner()
Returns the working copy owner of this working copy. Returns null if it is not a working copy or if it has no owner. 
Returns: 
WorkingCopyOwner the owner of this working copy or null 
Since: 
3.0


It says it returns "null" if it has no owner which is deceptive since when ( isWorkingCopy() && getOwner()==null) == true that means it's a primary working copy owner. 

Reproducible: Always
Comment 1 Dani Megert CLA 2009-10-30 03:42:54 EDT 
Agree, could be clarified.
Comment 2 Olivier Thomann CLA 2009-11-10 14:43:44 EST 
Created attachment 151872 [details]
Proposed fix

Would this make it clearer ?
Comment 3 Min Idzelis CLA 2009-11-10 15:02:09 EST 
I'm still confused by the text. 

What about:

@return <tt>null</tt> if this <code>ICompilationUnit</code> is the primary working copy, or this <code>ICompilationUnit</code> is not a working copy, otherwise the <code>WorkingCopyOwner</code>.

In the proposed text, it seems that null can have two meanings if it is a working copy.
Comment 4 Min Idzelis CLA 2009-11-10 15:04:58 EST 
Honestly, a new API method named isPrimaryWorkingCopy() seems like a good addition. It would return true if it is a working copy AND primary, false otherwise.
Comment 5 Olivier Thomann CLA 2009-11-10 15:21:14 EST 
(In reply to comment #4)
> Honestly, a new API method named isPrimaryWorkingCopy() seems like a good
> addition. It would return true if it is a working copy AND primary, false
> otherwise.
I opened bug 294804 for this.
Comment 6 Olivier Thomann CLA 2009-11-11 09:26:27 EST 
Created attachment 151940 [details]
Proposed fix

Here is the new patch based on last proposal.
Comment 7 Olivier Thomann CLA 2009-11-11 09:32:57 EST 
Released for 3.6M4.
Comment 8 Ayushman Jain CLA 2009-12-08 01:34:22 EST 
Verified for 3.6M4.