New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
lorenzwalthert opened this Issue Aug 3, 2018 · 5 comments

Comments

Projects
None yet
2 participants
@lorenzwalthert
Collaborator

lorenzwalthert commented Aug 3, 2018

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

This comment has been minimized.

Member

krlmlr commented Aug 23, 2018

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

@krlmlr

This comment has been minimized.

Member

krlmlr commented Aug 23, 2018

@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

This comment has been minimized.

Collaborator

lorenzwalthert commented Aug 23, 2018

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

This comment has been minimized.

Collaborator

lorenzwalthert commented Aug 29, 2018

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

@lorenzwalthert

This comment has been minimized.

Collaborator

lorenzwalthert commented Nov 4, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment