Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 363703

Summary: Typo in Javadoc for Diagnostic class
Product: [Modeling] EMF Reporter: Hernan Gonzalez <hjg.com.ar>
Component: CoreAssignee: Ed Merks <Ed.Merks>
Status: CLOSED FIXED QA Contact:
Severity: minor    
Priority: P3    
Version: unspecified   
Target Milestone: ---   
Hardware: All   
OS: All   
Whiteboard:

Description Hernan Gonzalez CLA 2011-11-14 09:58:01 EST 
Build Identifier: 20110916-0149

org.eclipse.emf.common.util.Diagnostic has two errors in documentation (javadoc) for fields ERROR and CANCEL , they both say 

 "bit mask value 0x1" 

where they should say 

 "bit mask value 0x4" 

 "bit mask value 0x8" 

respectively



Reproducible: Always
Comment 1 Hernan Gonzalez CLA 2011-11-14 10:12:00 EST 
Further, the documentation and values for this 'severity' field implies that it should be intepreted as a bitmask  (eg, are not necesarily exclusive, and they could be ORed), but reality says other thing: the values are exclusive, tests are make by equality. This is not really a bitmask, and setting, eg,  'severity = ERROR | WARNING' would break everything (see eg. ValidateAction.handleDiagnostic() , etc)
Comment 2 Ed Merks CLA 2011-11-14 12:10:07 EST 
It's documented in much the same was as IStatus.  Do you think it's documented in a misleading way too?
Comment 3 Hernan Gonzalez CLA 2011-11-14 12:37:03 EST 
(In reply to comment #2)
> It's documented in much the same was as IStatus.  Do you think it's documented
> in a misleading way too?

Yes - rather, it's not only a documentation issue but an (old, I guess) interpretation issue. The constants defined as bitmasks ( 1 ,2  4 ,8 ) are normally used for "OR-able" case, as non-exclusive flgas (where it's implied that a status could be a ERROR and also a WARNING, and the correct way of finding out if it's an error would be (severity & ERROR) != 0). This was perhaps the original idea, but it's not current idea; as today, those constants could have been defined as (1,2,3,4...). It seems error prone to me, perhaps the doc should at least remove the "bitmask" word (and don't mention the concrete value) so that instead of

Status type severity (bit mask, value 4) indicating this status represents an error

it just says

Status type severity indicating this status represents an error
Comment 4 Ed Merks CLA 2011-11-22 05:26:48 EST 
The changes are available in builds.