ENH Update DataObject::delete() docblock

[emteknetnz]

Issue https://github.com/silverstripe/silverstripe-linkfield/issues/213

I believe this is accurate, though please double check with a quick manual test before merging

[emteknetnz]

Possibly is, though I'm not sure. Versioned::doArchive() will do stuff in a nice orderly fashion such as managing changesets and unpublishing live version first, creating a nice history of deleted versions, etc

delete() is kind of crude and won't do any of that. If we changed delete() to also remove from the live stage then we now have 2x ways to remove things from the live stage - delete() and doArchive(). In my mind it's much better to only have a single way to do this, in this case it would be doArchive()

Also worth nothing that Versioned::deleteFromStage() has this:

    public function deleteFromStage($stage)
    {
       // ...
        static::withVersionedMode(function () use ($stage, $owner) {
            Versioned::set_stage($stage);
            $clone = clone $owner;
            $clone->delete();
        });

i.e. it's assuming that it's only going to delete() from a single stage, so if we changed delete() to delete from both stages then this method now has undesidered side effects. There may be well plenty more like this in the codebase.

So I think we should stick with this PR and just update the docblock

[GuySartorelli]

I would agree, except that both this PHPDoc and the official docs have been telling people they can just call delete() and it'll correctly archive the record.

At the very very least we need to update those docs and call out (probably in the changelog) that "hey you've been archiving records wrong because we told you to, sorry!"

This is probably a decision that needs to go through refinement at least though, if not an architecture discussion.

[emteknetnz]

I've spun off a new issue - I'll remove this PR from the original issue and attach it to the new one

Note the other PR on the original issue is still required as it also updates the owner

[GuySartorelli]

Setting to draft pending discussion on the new issue