`@title` tag adds `"\n"`

[TanguyBarthelemy]

I've noticed that when you add the @title tag to an R documentation page, {roxygen2} adds a "\n" (one for each skipped line) immediately after it in the raw element:

waldo::compare(
    roxygen2::parse_text("#' @title My function
#'
#' @description its description.
#'
NULL"), 
    roxygen2::parse_text("#' My function
#'
#' @description its description.
#'
NULL")
)
#> `names(old[[1]]$tags[[1]])`: "file" "line" "tag" "raw" "val"
#> `names(new[[1]]$tags[[1]])`: "file" "line" "raw" "tag" "val"
#> 
#> `old[[1]]$tags[[1]]$line` is an integer vector (1)
#> `new[[1]]$tags[[1]]$line` is a double vector (1)
#> 
#> `lines(old[[1]]$tags[[1]]$raw)`: "My function" ""
#> `lines(new[[1]]$tags[[1]]$raw)`: "My function"

Why is that?

Also, when skipping multiple lines after the title, if the @title tag is present, {roxygen2} generates a warning; otherwise, it does not.

roxygen2::parse_text("#' @title My function
#'
#'
NULL")
#> ✖ <text>:1: @title must be a single paragraph.
#> [[1]]
#> <roxy_block> [<text>:4]
#>   $tag
#>     [line:  1] @title 'My function...' {parsed}
#>     [line:  4] @backref '<generated>' {parsed}
#>   $call   NULL
#>   $object NULL
#> 
roxygen2::parse_text("#' My function
#'
#'
NULL")
#> [[1]]
#> <roxy_block> [<text>:4]
#>   $tag
#>     [line:  1] @title 'My function' {parsed}
#>     [line:  4] @backref '<generated>' {parsed}
#>   $call   NULL
#>   $object NULL
#> 

^{Created on 2026-04-14 with reprex v2.1.1}

Is this a problem?

[hadley]

Those lines aren't skipped; they're part of the title — in roxygen, a tag doesn't end until it hits the beginning of the next tag. So to me this looks like it's acting as designed? Is this causing a problem somehow?

[TanguyBarthelemy]

Ok, thank you. Actually, it’s not a problem at all. I was just wondering why, with or without @title, the function handled empty lines differently (in the raw element).

[hadley]

Yeah, it's because without title, the description parsing is more automatic/magical.