Description Maxime Daniel 2008-02-06 04:16:49 EST

Source based, v_835.

The 'This flag is only valid if the element is...' proposition in flags documentation is odd for the following reasons:
- it is the single case in all JDT APIs where it does not match a sense of acceptability; in fact, users are perfectly free to use any of those flags to query a delta; but only some deltas will be sensitive to such or such flag;
- it fails to convey the fact that the flag will be zero when non significant.

Having discussed a bit the issue with Jérôme, and having checked that our (JDT Core) APIs and Eclipse help in general do relate 'valid' to some sense of acceptability, I would contend that we should consider changing that. Moreover, we should find some means to convey the idea that not all elements that have a given property will bear the considered flag (for example, considering F_CONTENT, not all elements that correspond to files will get it set, some of them will get it unset). I would suggest something along the following lines:

	/**
	 * Change flag indicating that the content of the element has changed.
	 * This flag only gets positioned for elements which correspond to files.
	 */
	public int F_CONTENT = 0x000001;

or even more explicit:
	/**
	 * Deltas which elements correspond to files will get this flag set 
         * if and only if the content of the elements has changed.
	 */
	public int F_CONTENT = 0x000001;
(may have to fix the plurals in this one depending on the concrete cardinality of delta-element-file relationships).
More verbose even:
	/**
	 * Deltas which elements correspond to files will get this flag switched
         * on if and only if the content of the elements has changed. Other 
         * deltas always have it switched off.
	 */
	public int F_CONTENT = 0x000001;