Skip to content
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

Work around empty example lines #1085

Merged
merged 4 commits into from
Dec 26, 2022
Merged

Conversation

krlmlr
Copy link
Member

@krlmlr krlmlr commented Dec 26, 2022

Closes #1084.

@krlmlr
Copy link
Member Author

krlmlr commented Dec 26, 2022

Output has changed for two existing tests, but I believe the new behavior is correct.

Empty lines and comments inside examples are a hassle, would it be a big stretch if we ignored such examples entirely (except when last lines are empty)?

@codecov-commenter
Copy link

Codecov Report

Merging #1085 (b1f6848) into main (93914e4) will increase coverage by 0.00%.
The diff coverage is 100.00%.

@@           Coverage Diff           @@
##             main    #1085   +/-   ##
=======================================
  Coverage   91.10%   91.10%           
=======================================
  Files          46       46           
  Lines        2698     2699    +1     
=======================================
+ Hits         2458     2459    +1     
  Misses        240      240           
Impacted Files Coverage Δ
R/roxygen-examples.R 98.46% <100.00%> (+0.02%) ⬆️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

@github-actions
Copy link
Contributor

This is how benchmark results would change (along with a 95% confidence interval in relative change) if 93914e4 is merged into main:

  •   :ballot_box_with_check:cache_applying: 48.6ms -> 48.5ms [-3.27%, +2.76%]
  •   :ballot_box_with_check:cache_recording: 867ms -> 867ms [-2.15%, +2.28%]
  •   :ballot_box_with_check:without_cache: 2.06s -> 2.05s [-2.91%, +1.58%]

Further explanation regarding interpretation and methodology can be found in the documentation.

@lorenzwalthert
Copy link
Collaborator

lorenzwalthert commented Dec 26, 2022

Empty lines and comments inside examples are a hassle, would it be a big stretch if we ignored such examples entirely (except when last lines are empty)?

I think I don't think styler should remove blank lines here.

#' @export
#' @examples
#' a + b
#'
#' # here I put a comment
#' 2 + 1
#'
NULL

Why should the styling of previousl lines depend on the last lines being empty? And are you referring to a line in the examples (like #' ) or a completely blank line (like the one after NULL)?

@lorenzwalthert lorenzwalthert merged commit cb09801 into main Dec 26, 2022
@lorenzwalthert lorenzwalthert deleted the b-1084-empty-example-lines branch December 26, 2022 21:39
@krlmlr
Copy link
Member Author

krlmlr commented Dec 27, 2022

I'm referring to the following case:

#' @export
#' @examples
#' a + b
#'
# here I put a comment
#' 2 + 1
#'
NULL

What should we do with that comment? Perhaps a warning 😱 that we can't process this, with accurate file+line information?

@IndrajeetPatil
Copy link
Collaborator

Yeah, this is definitely a tricky case.

The clearest usage of regular comments I can see with the Roxygen blocks is to add annotations to ignore some code from being styled. For example, if I have a few examples in the docs, maybe I want some to be styled, while others not because I have custom formatting (example in the wild).

For example:

"#' @export
#' @examples
#' 
#' # example code I want styled
#' x = 1
#' y = 2
#' 
#example code I want styler to skip to preserve alignment
# styler: off
#' a   = 1
#' ab  = 2
#' abc = 3
#styler: on
NULL" -> code

styler::style_text(code)
#> #' @export
#> #' @examples
#> #'
#> #' # example code I want styled
#> #' x <- 1
#> #' y <- 2
#> #'
#> # example code I want styler to skip to preserve alignment
#> # styler: off
#> #' a   = 1
#> #' ab  = 2
#> #' abc = 3
#> # styler: on
#> NULL

Created on 2022-12-27 with reprex v2.0.2

As can be seen, currently, {styler} works as expected:
it styles the comments (note the newly added whitespace between # and example), and
it skips the code in @examples that is not expected to be styled.

IINM, if we stop processing the embedded comments, we will stop supporting this use case, right?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Blank lines for @examples are transformed to blank roxygen2 comments
4 participants