Error after devtools::document when #' comments inside function

[statnmap]

I would say this is linked to a bad practice but as I took me some time to find the reason, I thought this could be good to be reported.
I received a R code that I wanted to transform as a package. I remarked that if there are some comments inside a function that are commented with #', there are used as the roxygen skeleton. Hence, when using devtools::document() the following function returns a warning and is not exported. This because @export is followed by multiple lines.

Warning: @export [mean.R#11]: may only span a single line

Example function:

#' Mean of a vector

#' @param x vector
#'
#' @return return mean of a vector without NA
#' @import magrittr
#' @importFrom stats na.omit
#' @examples 
#' my_mean(c(4,5))
#' @export

my_mean <- function(x){
  #' Remove NA
  x <- x %>% na.omit()
  #' Calculate mean
  sum(x)/length(x)
}

To see it differently, we can finish the roxygen skeleton with @examples. Usually, if this is empty, document returns a warning: Warning: @examples [mean.R#9]: requires a value. However, in the following case, comments written using #' are used as the content of examples with no errors or warnings.

#' Mean of a vector

#' @param x vector
#'
#' @return return mean of a vector without NA
#' @import magrittr
#' @importFrom stats na.omit
#' @export
#' @examples 

my_mean <- function(x){
  #' Remove NA
  x <- x %>% na.omit()
  #' Calculate mean
  sum(x)/length(x)
}

Look at the documentation produced.

I think we are not supposed to include such kind of comments inside the function, but does roxygen not supposed to stop reading when calling function ? (Maybe it would not work with S3 methods or documented data ?)

Error reported here once is maybe linked:
STAT545-UBC/Discussion#241
and reported here
https://support.rstudio.com/hc/en-us/community/posts/205901678-Too-many-newlines-in-roxygen-comments

[hadley]

This was added in v5.0.0:

• The contents of documented functions are now also parsed for roxygen comments.
  This allows, e.g., documenting a parameter's type close to where this type is
  checked, or documenting implementation details close to the source, and
  simplifies future extensions such as the documentation of R6 classes
  (Allow roxygen comments in object to be documented #397, @krlmlr).