[Roxygen-devel] Roxygen & S4

[Hadley Wickham]

Hi all,

I've been working on a minimal set of changes to roxygen2 to get it
working with S4 classes. I have code that works but it needs broader
testing, so if you're using roxygen with S4 I'd really appreciate your
feedback. You can see the code at
https://github.com/klutometis/roxygen/tree/s4, or if you want to try
it out the easiest way is with the devtools package:

# install.packages("devtools")
library(devtools)
install_github("roxygen", "klutometis", "s4")

If you run into problems, please either respond to this email, or file
a bug on github: http://github.com/klutometis/roxygen/issues. Any work
you can do to reduce the problem to a simple example is really
appreciated - that makes it easier for me to create an automated test
case to ensure the bug doesn't recur.

Thanks!

Hadley

[Steve Lianoglou]

Thanks for taking the time to work on this, Hadley.

Is there an update "gold reference" for how we'd document S4 classes
(setClass) and method definitions? (setGeneric vs. setMethod)?

Are the hints found here still the right way to go, more or less?:

http://stackoverflow.com/questions/4396768/how-to-properly-document-s4-and-methods-using-roxygen

-steve

Post by Hadley Wickham
Hi all,
I've been working on a minimal set of changes to roxygen2 to get it
working with S4 classes. I have code that works but it needs broader
testing, so if you're using roxygen with S4 I'd really appreciate your
feedback. You can see the code at
https://github.com/klutometis/roxygen/tree/s4, or if you want to try
# install.packages("devtools")
library(devtools)
install_github("roxygen", "klutometis", "s4")
If you run into problems, please either respond to this email, or file
a bug on github: http://github.com/klutometis/roxygen/issues. Any work
you can do to reduce the problem to a simple example is really
appreciated - that makes it easier for me to create an automated test
case to ensure the bug doesn't recur.
Thanks!
Hadley
--
Assistant Professor / Dobelman Family Junior Chair
Department of Statistics / Rice University
http://had.co.nz/
_______________________________________________
Roxygen-devel mailing list
Roxygen-devel at lists.r-forge.r-project.org
https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/roxygen-devel

[Hadley Wickham]

Post by Steve Lianoglou
Is there an update "gold reference" for how we'd document S4 classes
(setClass) and method definitions? (setGeneric vs. setMethod)?
http://stackoverflow.com/questions/4396768/how-to-properly-document-s4-and-methods-using-roxygen

Yes, that's ok, but you shouldn't need to manually set the rdname
(it's a bug if you do), and @slot isn't supported yet. I'll try and
add that before we release the next version.

Hadley

[Hadley Wickham]

Post by Hadley Wickham

Post by Steve Lianoglou
http://stackoverflow.com/questions/4396768/how-to-properly-document-s4-and-methods-using-roxygen

Yes, that's ok, but you shouldn't need to manually set the rdname
add that before we release the next version.

And now @slot is supported.

Hadley

[Steve Lianoglou]

Post by Hadley Wickham

Post by Steve Lianoglou
http://stackoverflow.com/questions/4396768/how-to-properly-document-s4-and-methods-using-roxygen

Yes, that's ok, but you shouldn't need to manually set the rdname
add that before we release the next version.

Nice!

Thanks,
-steve

[Steve Lianoglou]

Hadley,

Sorry for pestering, but what's the right way to comment a setGeneric
and its derivatives, eg:

##' Make your object think
##'
##' We are building self aware objects
##'
##' @export
##'
##' @param x The object to make smarter
setGeneric("pontificate", function(x, ...) standardGeneric("pontificate"))

##' <how do we specify `something` specific behavior?
##'
##' (or do we not do that and comment the setGeneric as ferociously as
possible?)
setMethod("pontificate", c(x="something"), function(x, ...) {

})

Post by Hadley Wickham

Post by Steve Lianoglou
Is there an update "gold reference" for how we'd document S4 classes
(setClass) and method definitions? (setGeneric vs. setMethod)?
http://stackoverflow.com/questions/4396768/how-to-properly-document-s4-and-methods-using-roxygen

Yes, that's ok, but you shouldn't need to manually set the rdname
add that before we release the next version.
Hadley
--
Assistant Professor / Dobelman Family Junior Chair
Department of Statistics / Rice University
http://had.co.nz/

[Hadley Wickham]

On Mon, Feb 20, 2012 at 10:06 PM, Steve Lianoglou

Post by Steve Lianoglou
Hadley,
Sorry for pestering, but what's the right way to comment a setGeneric
##' Make your object think
##'
##' We are building self aware objects
##'
##'
setGeneric("pontificate", function(x, ...) standardGeneric("pontificate"))
##' <how do we specify `something` specific behavior?
##'
##' (or do we not do that and comment the setGeneric as ferociously as
possible?)
setMethod("pontificate", c(x="something"), function(x, ...) {
})

Just like that? What are you expecting that's not happening? If you
want the method to be documented inside the generic, you'd also need
@rdname pontificate

Hadley

[meik michalke]

hi,

shouldn't docs for generics also have a usage section? mine somehow don't.

roxygenizing this file:

<rxTest.R>
#' Test method
#'
#' Just a test. Where's the usage section?
#'
#' @param object An object of class \code{numeric}.
#' @keywords methods
#' @export
#' @docType methods
#' @rdname rxTest-methods
setGeneric("rxTest", function(object){standardGeneric("rxTest")})

#' @aliases rxTest,numeric-method
#' @rdname rxTest-methods
setMethod("rxTest", signature(object="numeric"), function(object){
print(object)
})
</rxTest.R>

gives me this:

<rxTest.Rd>
\docType{methods}
\name{rxTest}
\alias{rxTest}
\alias{rxTest,numeric-method}
\title{Test method}
\arguments{
\item{object}{An object of class \code{numeric}.}
}
\description{
Just a test. Where's the usage section?
}
\keyword{methods}
</rxTest.Rd>


defining @usage manually didn't help, the section remains omitted. :: m.eik
--
dipl. psych. meik michalke
institut f"ur experimentelle psychologie
abt. f"ur diagnostik und differentielle psychologie
heinrich-heine-universit"at d-40204 d"usseldorf
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.r-forge.r-project.org/pipermail/roxygen-devel/attachments/20120325/e20230b0/attachment.pgp>

[Hadley Wickham]

Could you please file a bug report?
Thanks,
Hadley

On Sun, Mar 25, 2012 at 1:24 PM, meik michalke

Post by meik michalke
hi,
shouldn't docs for generics also have a usage section? mine somehow don't.
<rxTest.R>
#' Test method
#'
#' Just a test. Where's the usage section?
#'
setGeneric("rxTest", function(object){standardGeneric("rxTest")})
setMethod("rxTest", signature(object="numeric"), function(object){
?print(object)
})
</rxTest.R>
<rxTest.Rd>
\docType{methods}
\name{rxTest}
\alias{rxTest}
\alias{rxTest,numeric-method}
\title{Test method}
\arguments{
?\item{object}{An object of class \code{numeric}.}
}
\description{
?Just a test. Where's the usage section?
}
\keyword{methods}
</rxTest.Rd>
--
dipl. psych. meik michalke
institut f"ur experimentelle psychologie
abt. f"ur diagnostik und differentielle psychologie
heinrich-heine-universit"at d-40204 d"usseldorf