Work around empty example lines

[krlmlr]

Closes #1084.

[krlmlr]

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]

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%)	:arrow_up:

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

[github-actions[bot]]

This is how benchmark results would change (along with a 95% confidence interval in relative change) if 93914e45e3fa3cccc318f17b4bc876acc1182f74 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]

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)?

[krlmlr]

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]

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?