Should ?drive_upload:overwrite mention drive_put?

[MichaelChirico]

I am trying to write a script that saves a plot to drive; of course with plots, small tweaks are part & parcel of the job.

That means drive_upload() is probably inappropriate for my use case, though I'm accustomed to using it as my default go-to function so I'm most used to it.

Thus my journey to discovering drive_put():

1. Use drive_upload() [implicitly using the overwrite=NA default]. Oh crap, the re-run just created a new file with the same! Is there an overwrite parameter I should be using?
2. Glance at ?drive_upload. Yes! OK Let's try overwrite=TRUE.
3. Looks good! Let's share this file. [Add the right permissions]. Oh crap, the re-run creates a new drive ID... which means the permissions I so painstakingly added were lost! Is that expected behavior?
4. [Actually read overwrite carefully this time]. Oh, that's unfortunate... do I have to wait until the plot is finalized to set the permissions, then, to avoid this toil? That's unfortunate. Is it not possible to transfer the permissions over?
5. [Check the Google Drive API... Check the {googledrive} issue tracker... Happen to see drive_update() mentioned for the first time] Oh, I guess I should be using drive_update()... but what about the initial upload? Oh, ?drive_update() mentions drive_put().

I've only just now noticed that drive_put() is mentioned at the top of ?drive_upload, oops :)

All this to say, is there any downside to adding another mention of drive_update() and/or drive_put() under the description of overwrite?

https://github.com/tidyverse/googledrive/blob/74a69a3a1fd66e930802ce6e461538c9e15f7c86/man-roxygen/overwrite.R#L8-L12

e.g.

...Note that the new file does not inherit any properties from the old one, such as sharing or publishing settings. It will have a new file ID. If you need to keep permissions and the file ID, use [drive_update()] or [drive_put()]. An error is thrown if two or more pre-existing files are found.

[MichaelChirico]

Another thought: It might help beginners to see drive_update()/drive_put() mentioned in this output too?

https://github.com/tidyverse/googledrive/blob/74a69a3a1fd66e930802ce6e461538c9e15f7c86/R/utils-paths.R#L59-L61