Update Javadoc for Deletable.delete()

[manusa]

          > The Javadoc for `Deletable` contain:

It is not guaranteed that the returned list will contain all values marked for deletion - see Issue #3058

It's not clear if this issue was fixed (in which case the above text should be removed from the Javadoc), or what the list can/will contain if this is not the case... Can you please elaborate? Thank you.

OK, so this Javadoc is a little bit unclear and probably outdated.

Its verbosity is mostly because there was a change in the method return type (from boolean to the List<StatusDetails>) some time ago.
Users were relying on the boolean response to assert that a resource was actually deleted.

However, there is no guarantee (from the Kubernetes API server) that a resource will be deleted if a DELETE request is performed against such resource.

In order to make sure that a resource is deleted, you need to check that it's marked for deletion (has a deletionTimestamp) and that all the finalizers have been cleared.
Eventually, the resource will be deleted.

To ensure that a resource is deleted you'd need a further check such as:

client.pods().withName($name).waitUntilCondition(Objects::isNull, 60, TimeUnit.SECONDS);

client.pods().withName($name).withTimeout(60, TimeUnit.SECONDS).delete();

We can probably remove the reference to this PR and add a few extra tips to the Javadoc.

/cc @shawkins

Originally posted by @manusa in #3058 (comment)

[manusa]

#3058 (comment)