[R-pkg-devel] Documenting S4 generic does not show usage

[Hadley Wickham]

1. Depends on whether you're documenting the method or the generic.
2. You don't
3. I can never remember. I think if it's your generic, you only need
it in one place.

Hadley

On Mon, Mar 21, 2016 at 11:06 AM, Manny Calavera <olbapjose at gmail.com> wrote:
> Thank you so much, it works like a charm :-)
>
> I would appreciate if you could please answer (very briefly) questions 1 to
> 3, so I can learn how to correctly document S4 generics properly in the
> future.
>
> Thanks again.
>
> 2016-03-18 15:11 GMT+01:00 Hadley Wickham <h.wickham at gmail.com>:
>>
>> The problem seems to be your use of methods::setMethod instead of
>> setMethod (etc). Roxygen2 doesn't seem to be quite smart enough to
>> realise that these aren't equivalent. You might want to file an issue
>> on github so I look into this the next time I'm working on roxygen2.
>>
>> Hadley
>>
>> On Fri, Mar 18, 2016 at 7:20 AM, Manny Calavera <olbapjose at gmail.com>
>> wrote:
>> > Good day to everyone,
>> > I have an issue when documenting an S4 generic. I have the following in
>> > my
>> > file generics.R:
>> >
>> > #' @rdname myfunction-methods#' @name myfunction <- without this,
>> > roxygen2 complaints about missing name#' @export
>> > methods::setGeneric("myfunction",
>> >   function( arg1, arg2 ),
>> >       arg3, arg4 {
>> >         methods::standardGeneric("myfunction")});
>> >
>> > and then in my file mymethods.R:
>> >
>> > #' Something#'#' A brief description#'#' @param all params... #'
>> > @return Something#' @name myfunction <- without this, roxygen2
>> > complaints on missing name#' @include generics.R#' @rdname
>> > myfunction-methods#' @export
>> > methods::setMethod( "myfunction",
>> >   methods::signature( arg1 = "formula", arg2 = "data.frame" ),
>> >   function( arg1, arg2, arg3, arg4 ) {
>> >
>> >    ...whatever
>> >     })
>> >
>> > With this, everything is fine except that the usage section is not
>> > showing
>> > up. Could you please correct what is wrong in my documentation? More
>> > precisely:
>> >
>> >    1.
>> >
>> >    Is it correct to write the documentation before setMethod or is it
>> >    preferably before setGeneric ?
>> >    2.
>> >
>> >    Why do I need the @name in both files? Should it be different? Does
>> > it
>> >    matter?
>> >    3.
>> >
>> >    Do I need @export in both files?
>> >    4.
>> >
>> >    Would @alias help at all?
>> >
>> > I tried reading Hadley Wickham's section on how to document S4 functions
>> > but did not help (probably I didn't understand something correctly).
>> >
>> > Thank you very much in advance.
>> >
>> >         [[alternative HTML version deleted]]
>> >
>> > ______________________________________________
>> > R-package-devel at r-project.org mailing list
>> > https://stat.ethz.ch/mailman/listinfo/r-package-devel
>>
>>
>>
>> --
>> http://hadley.nz
>
>



-- 
http://hadley.nz