WISH: Support comments in tags

[HenrikBengtsson]

trafficstars

I wanted to add a comment to one specific roxygen2 tag, and tried:

#' @importFrom future future  ## dummy import to please 'R CMD check'

but roxygen2 parses those as symbols to be imported;

importFrom(future,journal)
importFrom(future,"##")
importFrom(future,"'R")
importFrom(future,"check'")
importFrom(future,CMD)
importFrom(future,dummy)
importFrom(future,future)
importFrom(future,import)
importFrom(future,please)
importFrom(future,to)

I've also tried using Rd comment symbol %, but same thing;

#' @importFrom future future  % dummy import to please 'R CMD check'

Please consider supporting comments following tags.

Of course, the following works:

#  ## dummy import to please 'R CMD check'
#' @importFrom future future

[hadley]

I assume it's ok to just discard the comments? They don't need to be propagated into the NAMESPACE?

[HenrikBengtsson]

Yes, discarding comment is what I'd expect from this.

(Though, interesting idea to propagating them to NAMESPACE. But, that feels like a rare use case.)

[TimTaylor]

Further to this discussion and to add another use case for this:

I often use comment lines, without commentary, to break up my code (e.g. # ------------- ). This makes it easier for my eyes to scan through different sections quickly. It would be great to have a similar ability within roxygen based function documentation where I'm often wanting to break up longer details/parameter sections with more than just white-space.

[gaborcsardi]

@TimTaylor I believe you can already do that, and roxygen2 ignores "regular" comments, even among #' lines.

[TimTaylor]

@gaborcsardi - we may have crossed wires. I'm after something that wouldn't render (e.g. purely for styling the source documentation). The following:

#' my title
#'
#' my description
#'
#' my details
#'
#' #-----------------
#'
#' @param x my param
#'
#' #-----------------
#'
#' @export
demoroxy <- function(x) x

renders for me as

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/demoroxy.R
\name{demoroxy}
\alias{demoroxy}
\title{my title}
\usage{
demoroxy(x)
}
\arguments{
\item{x}{my param

#-----------------}
}
\description{
my description
}
\details{
my details

#-----------------
}

[gaborcsardi]

I meant

#' my title
#'
#' my description
#'
#' my details
#'
#-----------------
#'
#' @param x my param
#'
#-----------------
#'
#' @export
demoroxy <- function(x) x

[TimTaylor]

@gaborcsardi - amazing! Apologies for the noise on the issue - I had no idea this was possible. Do you want to hide the comments?