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
