Improving .Rd doc for DSL and target()

[lorenzwalthert]

Prework

• Read and abide by drake's code of conduct.
• Search for duplicates among the existing issues, both open and closed.

Description

I think the DSL in drake is interesting, but it is hard to learn how to use it. Lets take this example from the drake manual:

 drake_plan(
  data = get_data(),
  analysis = target(
    fun(data, mean = mean_val, sd = sd_val),
    transform = cross(mean_val = c(2, 5, 10, 100, 1000), sd_val = !!lots_of_sds)
  )
)

Neither does ?target, tell me about the argument transform nor can I use ?cross and similar for other DSL verbs to get to the documentation for these functions. They are very much magic to me. I consider the R documentation system a core strength of the eco system and hence I'd propose to extend the documentation in that regard. If ... is used in target(), then at least the doc could say where to look for the argument names if possible. Ideally adding examples to the Rd doc, but even linking to the drake manual could be an improvement of the status quo I think. Thanks for making this package so great.

[wlandau]

Yeah, I agree to extend the docs. map(), cross(), etc. are not actually functions, and target() is no longer supposed to be a user-side function, but we should still add *.Rd files.

[lorenzwalthert]

Great, thanks a lot @wlandau.

[wlandau]

Reconsidering how we implement this. Problems:

1. Name conflicts with true functions, e.g. purrr::map().
2. Function arguments will be different in dynamic branching.

[lorenzwalthert]

what about adding a prefix to the functions and soft-depreciate the initial API? Like

• map -> dmap (or drake_map())
• cross -> dcros
• etc.

I think for many this is a source of confusion.

[wlandau]

The current drake::map() etc. just throw an informative error, so I do not think there is anything meaningful to deprecate here. The help links like ?map will still work.