Pretty-printting of function call in Usage section in .Rd

[lorenzwalthert]

Rendered help files for multi-line function calls have a Usage section that look like the one (taken from for dplyr::join()):

# S3 method for class 'tbl_df'
inner_join(x, y, by = NULL, copy = FALSE,
  suffix = c(".x", ".y"), ...,
  na_matches = pkgconfig::get_config("dplyr::na_matches"))

I think developers should potentially have control over how their Usage section is printed. In particular, to make it compliant with their style guide of choice. As the primary style guide supported by styler is the tidyverse style guide, this should rather look like this:

# S3 method for class 'tbl_df'
inner_join(x, y,
  by = NULL, copy = FALSE,
  suffix = c(".x", ".y"), ...,
  na_matches = pkgconfig::get_config("dplyr::na_matches")
)

Manually changing the .Rd source and re-building a package, I noted that line breaks in \usage{} are respected, which means we could in principle apply an arbitrary style guide to the code before writing to the .Rd. In other words, styler could be used to tidy up the code. We could let users opt-in for the tidyverse compliant styling via the roxygen field in DESCRIPTION that is already used for other options.

Roxygen: list(
      markdown = TRUE, 
      roclets =  c("rd", "namespace", "collate", "pkgapi::api_roclet", "styler::style_usage_roclet")
)

@krlmlr implemented https://github.com/r-lib/pkgapi that uses this field. Maybe you @krlmlr could support us develop this feature as you are already experienced with this? Should be a quick shot. Alternatively, this feature could be implemented in roxygen itself. Don't know what the best place is, happy to discuss.

Also, for this to not end in a one-line formatting, we potentially need styler to be able to break long lines (as WIP at #390 ) if roxygen does not handle that before with the rd roclet.

On a related note: We recently implemented styling of roxygen example code source in #381.

[krlmlr]

I don't remember the details of the pkgapi roclet, it's all in the code ;-)

[krlmlr]

@hadley: Should we format usage sections with styler in roxygen2? My gut feeling is that it would be orders of magnitude easier to implement styling of usage sections in roxygen2 (and not as an external roclet), but that would bring in styler as a dependency.

[lorenzwalthert]

If I am correct, this would extend the roxygen2 dependency graph as follows:

setdiff(
  miniCRAN::pkgDep("styler", availPkgs = available.packages(), suggests = FALSE),
  miniCRAN::pkgDep("roxygen2", availPkgs = available.packages(), suggests = FALSE)
)
#>  [1] "styler"   "enc"      "rematch2"

^{Created on 2018-09-23 by the reprex package (v0.2.0.9000)}

[lorenzwalthert]

Alternatively, one could also just add the line break before the last brace with some other heuristic in roxygen2.

[lorenzwalthert]

As stated above, styler can't break long lines, but it's not a problem because we just had to apply styler to the current formatting, which already breaks the lines correctly (up to the fact that the first line should only contain unnamed arguments, which styler would then fix) I believe.

[lorenzwalthert]

Let's close this in favor of r-lib/roxygen2#820.