5

I'm writing a package with an S4 class, and I've written methods for as.POSIXct and as.POSIXlt for the class. I've written the documentation and everything looks fine, except that I would like to reference the as.POSIXct method in the documentation for as.POSIXlt, and vice versa. I tried \S4method{coerce}{abc, POSIXct}(from, to), (where 'abc' is the S4 class), but that is only supposed to be put in the \usage section, which isn't where I want it. Is there a way to do this? It seems odd to me that it would not be allowed.

I realize that it is possible to combine these .rd files and avoid this issue, but I'm trying to learn as much as possible about classes and packages in R, so this is of interest to me anyway.

Here is the skeleton of one of the .Rd files:

\name{as.POSIXct-methods}
\docType{methods}
\alias{as.POSIXct-methods}
\alias{as.POSIXct,ANY-method}
\alias{as.POSIXct,abc-method}
\title{\code{abc} Method for Function \code{as.POSIXct}}
\description{
\code{as.POSIXct} method to coerce timestamps in \code{abc} objects into 
\code{POSIXct} format.
}
\section{Methods}{
\describe{
~~description here~~

\item{\code{signature(x = "ANY")}}{
default implementation (from base)
}

\item{\code{signature(x = "abc")}}{
implementation for \code{\link{abc}} objects. 
~~more description of function~~
See \code{\linkS4class{abc}} for more about abc objects.
See also \code{\link[abc]{as.POSIXlt}} for the corresponding \code{POSIXlt} method.
}
}}
\keyword{methods}

The line fourth from the bottom is the one that is causing problems.

Eli Sander
  • 1,228
  • 1
  • 13
  • 29

2 Answers2

3

The basic format for a link is

\link{foo}

where foo appears in some help page (in the same package) as \alias{foo}. So if your other package has \alias{as.POSIXlt,abc-method} (pay attention to the absence of spaces) then

\link{as.POSIXlt,abc-method}

Adding [abc] is only necessary when linking to other packages, and then the semantics are confusing (in \link[abc]{foo}, foo is the name of the HTML help page, rather than, e.g., an alias). Adding \code{} is mark-up, so not directly relevant to establishing a link. The link above inserts "as.POSIXlt,abc-method" into the help page, which might be more informative (or not) than an arbitrary \alias tag that might be present.

Martin Morgan
  • 45,935
  • 7
  • 84
  • 112
2

Per the Cross-references section of Writing R extensions, you can create links to other help pages like this:

\code{\link[base]{as.POSIXct}}

Where "base" is the name of the package (I don't think [base] is necessary, but if it were another package, it would be)

GSee
  • 48,880
  • 13
  • 125
  • 145
  • Seconding, I don't think there's another way. – themel Aug 20 '12 at 19:28
  • I appreciate it! I read that section of WRE but I was a little confused, and I wasn't sure if it would work for what I wanted. Your explanation was very clear, thank you! – Eli Sander Aug 20 '12 at 19:30
  • Actually, the [Cross-references section](http://cran.r-project.org/doc/manuals/R-exts.html#Cross_002dreferences) is probably more appropriate. I will edit. – GSee Aug 20 '12 at 19:31
  • Actually, I'm getting a "missing link" warning when I run R CMD check. It's definitely not happy with the link I added. I think it must work differently for S4 methods... I thought specifying the package was what I needed to add, but apparently not. – Eli Sander Aug 20 '12 at 19:39
  • does it work if you just do `\code{\link{as.POSIXct}}`? Otherwise, you'll need to show more of you .Rd file – GSee Aug 20 '12 at 19:43
  • No, that's what I'd done originally, but when it gave me an error I looked through WRE and then put it on SO. I'll put up some example documentation in a second. – Eli Sander Aug 20 '12 at 19:46
  • Thanks for providing the .Rd file. The problem is `\code{\link[abc]{as.POSIXlt}}`. Compare that to my answer. – GSee Aug 20 '12 at 19:58
  • I'm not sure I see what you mean. 'abc' is both the name of the package and of the S4 class, so that should be what I want in the square brackets. – Eli Sander Aug 20 '12 at 20:00
  • So, you have another .Rd file in package abc with `\alias{as.POSIXlt}`? – GSee Aug 20 '12 at 20:01
  • And I was actually wrong, \code{\link{as.POSIXct}} should work, it just wouldn't do what I want. That would just link to the generic. I want to link to my method for 'abc' objects. – Eli Sander Aug 20 '12 at 20:01
  • Yes. I mentioned in the question that I have an `as.POSIXct` and an `as.POSIXlt` method, and I want each man page to refer to the other. They are both S4 methods for 'abc' objects. – Eli Sander Aug 20 '12 at 20:03
  • I'm on my way out the door, so this is my last guess: `\code{\link[abc]{as.POSIXlt-methods}}` – GSee Aug 20 '12 at 20:08
  • That did it! Apparently I never tried that particular variant in all of my experimentation. Thanks for the help! – Eli Sander Aug 20 '12 at 20:14