Improve documentation of "_raw" functions

[wlandau]

@hadley, in our brief conversation at Posit Conf, it seemed like you were referring to this specific issue at one point. For many functions, there are analogous "_raw" functions which don't quote their arguments. In tarchetypes, this almost doubles the size of the namespace. I do regret my decision about "_raw" and feel like I should have handled this through an argument. It's one of those huge cleanup things I felt I didn't have time for, but a wave of gentle deprecation probably needs to happen at some point.

targets::tar_target_raw() is used so for so many target factories that maybe just superseding it would be kinder.

[hadley]

Can you explain what _raw does? It's not obvious to me from quickly skimming the docs.

Looking again at the docs again, I think I might actually have been wondering why the actual targets don't have a common prefix, i.e. I would expect tar_target_quarto() etc. (I think I saw an issue on this but now I can't find it again).

[wlandau]

Can you explain what _raw does? It's not obvious to me from quickly skimming the docs.

When there is a pair of functions f() and f_raw(), the latter is a non-NSE version of the former. For example, tar_target(name = target_name, command = do_stuff()) is equivalent to tar_target_raw(name = "target_name", command = quote(do_stuff()). f() is easier for end users, and f_raw() is easier for building target factories. Also, f() usually calls f_raw() internally, kind of like how _impl is used.

I am not proud of the specific choice of suffix. By "raw", I only meant that the types of arguments feel lower level than in the non-"raw" version.

[wlandau]

Looking again at the docs again, I think I might actually have been wondering why the actual targets don't have a common prefix, i.e. I would expect tar_target_quarto() etc. (I think I saw an issue on this but now I can't find it again).

I can see why a "tar_target_" prefix might be useful for discovering target factories in a namespace, but target factory names can already get quite long, e.g. tar_stan_mcmc_rep_diagnostics(): https://docs.ropensci.org/stantargets/reference/index.html

[hadley]

In that case I'd suggest just using the _ suffix (since folks might remember that from an earlier version of tidy evaluation), and you should document the two variations of each function in the same file, with an explanation of the differences. I don't think it's a good idea to make this distinction with an argument because of https://design.tidyverse.org/independent-meaning.html. (This is one reason we developed tidy evaluation)