[API review] RT-30668: ClipboardContent has buggy API

[Pavel Safrata]

Hello,
ClipboardContent API contradicts itself and the documentation doesn't 
match the behavior.


Issue 1:
Every putSomething method documentation says:
  * Setting this value to null effectively clears it from the clipboard.
  * @throws NullPointerException if null reference is passed

We need to choose one of the two described behaviors. Currently the code 
throws NPE.
For some complicated content creation logic the clearing may be useful, 
so I propose to let the passed null reference clear the value.


Issue 2:
Every putSomething method documentation says:
   * @return True if the something was successfully placed on the clipboard.
And in other places it refers to "this clipboard". But this is not 
clipboard, it is the ClipboardContent which is later set to the 
Clipboard - and this operation returns the "successful" boolean.

So we definitely should rephrase the documentation. In the "putter", if 
we say
   * @return True if the something was successfully placed on the 
clipboard content.
then it needs to always return true (putting a reference to a map 
doesn't fail) which is not the case right now (right now the behavior is 
senseless, it returns true if the same thing is put there for the second 
time). As the "always true" is not really useful, and because of 
backward compatibility we can hardly change the return value to map's 
usual "previous value", we can consider at least redefining the boolean 
to something like "returns true if a previously added value was replaced".

What do you think? I'd probably go with the "always true", which not 
useful but at least quite intuitive. I would document it to return 
always true to spare users pointless checks.

Thanks,
Pavel