Why does the @family tag add dots between words in roxygen2?

Question

I am writing an R package and create documentation using roxygen2. I build the package and the documentation using the button Build & Reload in RStudio. According to RStudio's output, it uses devtools::document(roclets=c('rd', 'namespace')) to compile the documentation.

I want to use the @family tag to link together a number of functions in the documentation and this is where my problem occurs. This line

#' @family functions returning some object

is converted in the .Rd file to the following

\seealso{
    Other functions.returning.some.object: \code{\link{test2}}
 }

I don't want the dots between the words. I have an older package, where this does not happen, even if I recompile the documentation in the exact same setting as I compile the new package. I can see no fundamental difference between this older package and my new attempt.

I have written a very simple test package, where the problem also occurs. It contains a single R file (testpackage.R):

#' Test function 1
#' 
#' @param x a number
#' 
#' @family functions returning some object
#' @family aggregate functions
#' 
#' @export

test1 <- function(x) {
  x*x
} 


#' Test function 2
#' 
#' @param x a number
#' 
#' @family functions returning some object
#' @family aggregate functions
#'  
#' @export

test2 <- function(x) {
  x*x*x
}

The DESCRIPTION file is

Package: testpackage
Type: Package
Title: Package for testing purposes
Version: 1.0
Date: 2015-05-21
Author: Me
Maintainer: Me <[email protected]>
Description: Package for testing purposes
License: GPL-3

NAMESPACE is generated by roxygen. For the documentation test1.Rd, I get:

% Generated by roxygen2 (4.1.1): do not edit by hand
% Please edit documentation in R/testpackage.R
\name{test1}
\alias{test1}
\title{Test function 1}
\usage{
test1(x)
}
\arguments{
\item{x}{a number}
}
\description{
Test function 1
}
\seealso{
Other aggregate.functions: \code{\link{test2}}

Other functions.returning.some.object: \code{\link{test2}}
}

with the unwanted dots in the \seealso section. Clearly, the number of words in the @family tag seems not to matter. I have tried enclosing the text in quotation marks, various kinds of brackets, etc. with no positive effect. Of course, I could edit the Rd files, but this would miss the point of using roxygen2.

R CMD check runs without warnings or errors on testpackage.

Why do these dots appear? And how can I get rid of them?

Actually, I find that @family produces no output in my .Rd files, using Roxygen2-4.1.1 on R-3.2.3; possibly this is a feature only of as-yet-unreleased versions of Roxygen2. — dank
But it does produce output for me, so it can't be that this feature is not yet supported. I think, you need to add the same @family tag to at least two functions, in order to have output. — Stibu
Sorry, @Stibu, you're right on this. I now get the family information but with those ugly dots, like you're getting. — dank

Kevin Ushey Kevin Ushey · Accepted Answer · 2016-05-26T05:31:32

This is a bug in roxygen2 -- I've logged an issue here. It effectively results from the use of unstack(), which performs some unwanted conversions.

Why does the @family tag add dots between words in roxygen2?

2 Answers