roxygen2
roxygen2 copied to clipboard
r-lib
R6 methods shouldn't have crossreferences to base functions of the same name
The upcoming roxygen2 7.0 release adds new support for R6 classes, including generating doc entries for class methods. pkgdown is mistakenly interpreting these as any other code example and adding crossreference links to other packages' man pages.
In the arrow package, we have R6 classes that wrap file/connections in Arrow C++, and they have some methods that are the same name as base functions for working with connections in R. For example, roxygen2 created this Rd chunk for a method:
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-seek"></a>}}
\subsection{Method \code{seek()}}{
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{RandomAccessFile$seek(position)}\if{html}{\out{</div>}}
}
pkgdown rendered that as
<p><hr>
<a id="method-seek"></a></p><h3>Method <code><a href='https://rdrr.io/r/base/seek.html'>seek()</a></code></h3>
<h3>Usage</h3>
<p><div class="r"></p><pre>RandomAccessFile$seek(position)</pre><p></div></p>
The link to https://rdrr.io/r/base/seek.html shouldn't be there.
@gaborcsardi I realise this will probably require changes to roxygen2 😢
One simple hack would be to write \subsection{Method \code{$seek()}}.
Maybe it is possible to solve this in pkgdown? E.g. in an R6 reference page, method names should take priority over regular functions?
The autolinking code is complex and fragile, so that would be a lot of work.
Not sure whether this is related but I am also observing wrong cross-references when exported package names override base names, e.g. if a package has a function options, mentions of that function in pkgdown pages (including in the function’s own usage on its reference page, and even if the name is fully qualified, e.g. xyz::options, where xyz is the package name!) will link to https://rdrr.io/r/base/options.html.
By contrast, exported names that don’t conflict with those of other packages don’t appear to be linked at all.
Is this still a problem? downlit should no longer link anything in headings.
Hmmm the problem is that the linking done by the Rd processing, so autolinks the code snippet following the usual rules. Might need to think about the R6 problem a bit more holistically, since the subheadings also get repeated ids.
How about we put a $ in front of method names? I.e. it would become
\subsection{Method \code{$seek()}}{
and then I assume the auto-linker does not pick it up.