96

I am wondering it there exists a method to link to function from other package when I'm trying to write a documentation for new package using roxygen2. Something like \link{pck=PACKAGE_NAME, fun=FUNCTION_NAME}?

Marcin
  • 7,834
  • 8
  • 52
  • 99
  • 19
    Try `\code{\link[MASS]{stats}}`, from [here](http://r-pkgs.had.co.nz/man.html) (scroll way down). – joran Aug 25 '14 at 15:18
  • Thanks. Mb you know where could I find a full list of roxygen2 documentation parameters like what's stand for `@param` or `@family` or so on? There are many that I couldn't find info about them anywhere. [For example](http://stackoverflow.com/questions/25293137/chapters-in-r-reference-manual-and-documentation-using-roxygen2): – Marcin Aug 25 '14 at 15:22

5 Answers5

137

You have to type \link[pkg]{function} e.g. \link[stringi]{stri_c}

potockan
  • 3,998
  • 3
  • 25
  • 37
  • 9
    so short answer but so valuable :) – Marcin Jun 05 '18 at 11:07
  • 5
    note chapter "alternative documentation workflow" in [hadley's book](http://r-pkgs.had.co.nz/man.html). In order to see the links, you have to rebuild the package, not only re-document. – tjebo Mar 28 '20 at 13:09
48

Roxygen2 now also supports documentation written in markdown.

The markdown syntax is for the link is [foo::bar()] which is translated to \code{\link[foo:bar]{foo::bar()}} in the generated .Rd file. (See Roxygen2 vignette.)

Note that you may need to specifically turn on Markdown support by writing Roxygen: list(markdown = TRUE) in your DESCRIPTION file, or by putting an #' @md comment if you want to enable markdown only for a specific man page. This is also explained at the very top of the linked vignette. (Thanks to @Tjebo for the comment)

Note that there are two colons in the markdown version whereas there is only one colon in the Rd version.

cbeleites unhappy with SX
  • 13,717
  • 5
  • 45
  • 57
  • Wow, amazing!! Thanks – Marcin Dec 15 '19 at 17:28
  • Thank you for the note about enabling markdown! I've seen recommendations elsewhere about using markdown style links and was infuriated when I couldn't get them to work :facepalm: – mattador Jun 08 '22 at 22:06
45

There are two ways to achieve this, using:

1. .Rd syntax

From "R packages" book:

  • \code{\link{function}} - function in this package.
  • \code{\link[MASS]{abbey}} - function in another package.
  • \link[=dest]{name} - link to dest, but show name.
  • \code{\link[MASS:abbey]{name}} - link to function in another package, but show name.
  • \linkS4class{abc} - link to an S4 class.

2. markdown syntax

From roxygen2 vignette

roxygen2 comment description generated Rd code
[func()] func() in this package \code{\link[=func]{func()}}
[pkg::func()] func() in the pkg \code{\link[pkg:func]{pkg::func()}}
[thing] topic in this package \link{thing}
[pkg::thing] topic in the pkg \link[pkg:thing]{pkg::thing}
[`thing`] topic in this package \code{\link{thing}}
[`pkg::thing`] topic in the pkg \code{\link[pkg:thing]{pkg::thing}}

Remember to put Roxygen: list(markdown = TRUE) in the DESCRIPTION
Markdown shortcodes available from roxygen2>=6.0.0

GoGonzo
  • 2,637
  • 1
  • 18
  • 25
13

In addition to the answer by potockan:
Some packages document several functions in a single help page. For example, the trim function from Bioconductor package GenomicRanges is documented in intra-range-methods (which is also the name of a help page from other packages such as IRanges).

To link to the right page with roxygen2 you can use: 

\link[GenomicRanges:intra-range-methods]{trim}

or 

\code{\link[GenomicRanges:intra-range-methods]{trim}}

to format the text correctly.

The help page will only show trim but will link to the right help page.

Pascal Martin
  • 311
  • 2
  • 9
  • 1
    This was helpful when I wanted to link to the `dplyr` `dplyr_tidy_seelct` page. `\code{\link[dplyr::dplyr_tidy_select]{tidy-select}` resulted in a warning and broken link, but `\code{\link[dplyr:dplyr_tidy_select]{tidy-select}` worked. – LMc Feb 16 '22 at 18:16
0

To link to a function, we slightly abuse markdown syntax by using [function()] or [pkg::function()].

  • Re-document your package by pressing Cmd/Ctrl + Shift + D.

  • Build and install your package by clicking in the build pane or by pressing Ctrl/Cmd + Shift + B. This installs it in your regular library, then restarts R and reloads your package.

  • Preview documentation with ?

gbganalyst
  • 364
  • 4
  • 8