Prework

• Read and agree to the code of conduct and contributing guidelines.
• If there is already a relevant issue, whether open or closed, comment on the existing thread instead of posting a new issue.

Description

The help file documentation of the differences between tar_delete(), tar_destroy(), and tar_invalidate() don't make it clear when to use one vs another of those functions. I think that it would be helpful to change the text used on the help pages to talk about when they would be used in addition to how they affect the filesystem _targets/.

As an example, for tar_invalidate(), says that it will "Delete the metadata of records in _targets/meta/meta but keep the return values of targets in _targets/objects/." I found what those are in the design document where the disk format is described (https://books.ropensci.org/targets-design/data.html), but it's still not clear to me when I would want to remove the meta-data but keep the return value (i.e. when I would use tar_invalidate() vs tar_delete()).

Request

I think that it would be helpful to have tar_delete() and tar_invalidate() described a bit more clearly in their help pages. I think that easier-to-understand wording would be something like:

"Use tar_delete() when you want to remove the return value of a target and force it to be rerun."

and

"Use tar_invalidate() when ..." (I'm not sure when I'd want to use it. Maybe the description would be, "tar_invalidate() is not usually needed by a user of targets.")

I also think it would be useful to describe all of the target-removal functions in a single place. I didn't see it in the user manual, but maybe I missed it.