[ESS] Roxygen: arbitrary sections (@section)
Mathieu Basille
basille at ase-research.org
Mon Jan 30 18:40:31 CET 2012
Hello,
I'm new to the use of Roxygen with Emacs (actually new to writing
documentation at all!), so please apologize if it is a dumb question. I'd
like to add non-standard sections associated to the documentation. Using
the example of ESS doc [1], say I'd like to add a section 'Bli' with the
content 'blabla'. The Roxygen manual [2] recommend to use:
"@section Name: contents Use to add to an arbitrary section to the
documentation. The name of the section will be the content before the first
colon, and the contents will be everything after the colon."
Let's do so:
##' Description of the function
##'
##' Further details about this function
##' @title A title
##' @param me all parameters must be listed and documented
##' @return Description of the return value
##' @author The author
##' @section Bli: blabla
myfun <- function(me)
cat("Hello", me, "\n")
Previewing the Rd file (C-c C-e C-r) results in:
Warning in parse.warning(key, "is an unknown key") :
@section is an unknown key.
\name{myfun}
\alias{myfun}
\title{A title}
\usage{myfun(me)}
\description{Description of the function}
\details{Further details about this function}
\value{Description of the return value}
\author{The author}
\arguments{\item{me}{all parameters must be listed and documented}}
It seems that the @section is unknown to the Roxygen package for ESS. It
works, however, if I directly use the Roxygen package for R. I first save
the following myfun.Rd file:
\name{myfun}
\alias{myfun}
\title{A title}
\usage{myfun(me)}
\description{Description of the function}
\details{Further details about this function}
\value{Description of the return value}
\author{The author}
\arguments{\item{me}{all parameters must be listed and documented}}
\section{Bli}{blabla}
And then convert it to help text:
===================== R =========================
library(tools)
Rd2txt("myfun.Rd")
A title
Description:
Description of the function
Usage:
myfun(me)
Arguments:
me: all parameters must be listed and documented
Details:
Further details about this function
Value:
Description of the return value
Bli:
blabla
Author(s):
The author
===================== R =========================
Is there anything I can do to be able to use @section in Roxygen
documentation using Emacs?
Note: I use ESS 5.14 with Emacs 23.2.1 under Debian Stable, with R 2.14.1
and roxygen package for R 0.1-3.
Sincerely,
Mathieu Basille.
[1] http://ess.r-project.org/Manual/ess.html#Roxygen
[2] http://roxygen.org/roxygen2-manual.pdf
--
~$ whoami
Mathieu Basille, Post-Doc
~$ locate
Laboratoire d'Écologie Comportementale et de Conservation de la Faune
+ Centre d'Étude de la Forêt
Département de Biologie
Université Laval, Québec
~$ info
http://ase-research.org/basille
~$ fortune
``If you can't win by reason, go for volume.''
Calvin, by Bill Watterson.
More information about the ESS-help
mailing list