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?

googledrive/man-roxygen/overwrite.R

Lines 8 to 12 in 74a69a3

	#' * `TRUE`: Check for a pre-existing file at the filepath. If there is
	#' zero or one, move a pre-existing file to the trash, then carry on. 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. An error is
	#' thrown if two or more pre-existing files are found.

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?

googledrive/R/utils-paths.R

Lines 59 to 61 in 74a69a3

	if (overwrite && single_file(hits)) {
	return(drive_trash(hits))
	}

[jennybc]

For anyone from tidy dev day, I'd be happy to get a PR with a documentation change along the lines of the message that starts this thread.