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

[Richard Bair]

> 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.

Sounds fine (I prefer not having the exception for sure).

> 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.

I agree.

Thanks
Richard