JOSS review - function documentation

[debruine]

Review issue: openjournals/joss-reviews#4707
Branch reviewed: main

All function documentation I've seen assumes the main package is already loaded. It is unusual and unnecessary to begin all examples in the documentation with:

library(dplyr)
library(dtrackr)

Loading dplyr seems seldom necessary, and would probably be clearer if you use dplyr::func() to demark any functions that don't come from dtrackr in your examples. I tried all of the examples in the "Controlling dtrackr" section and none required dplyr (the %>% pipe is loaded with dtrackr).

[robchallen]

Right so... Had a few issues with this. There is a reason it is the way it is. The problem is that as I am writing S3 extensions to dplyr, that provide new specific method implementations for the tracked_df class - i.e. I am not overriding dplyr but extending it for a subclass of dataframes.

Hence all the examples call dplyr's methods first, and then are dispatched to the dtrackr S3 extension of that method, (e.g.) mutate calls in the examples go through dplyr::mutate() first, then if they are tracked data frames they will go to dtrackr::mutate.tracked_df() - which then untracks the data frame and dispatches back to dplyr for the main effect.

Anyway as a result the examples only work if they have dplyr explicitly imported otherwise they can't find the original mutate method to then be dispatched to the dtrackr method. If there is no library call the cases then fail in the R CMD check / devtools::check() context, when no other packages are loaded, although will usually work in a normal user level session because dplyr will have been loaded by something at some point.

I had a look around at how other packages did this but could not find an exact equivalent. I agree it is a little weird looking in the example though, and if you know a better way that still works in devtools::check() then I'd be interested.

I'm going to close this as a "can't fix" issue, but please reopen if you have a further concern.