W przypadku dokumentacji klas za pomocą roxygen (2) określenie tytułu i opisu / szczegółów wydaje się być takie samo, jak w przypadku funkcji, metod, danych itp. Jednakże szczeliny i dziedziczenie są ich rodzajem zwierząt. Jaka jest najlepsza praktyka - obecna lub planowana - do dokumentowania klas S4 w roxygen2?

Due Diligence:

We @slotwczesnych opisach roxygen znalazłem wzmiankę o znaczniku. Post z listy mailingowej R-forge z 2008 roku wydaje się wskazywać, że jest martwy i nie ma wsparcia dla @slotroxygen:

Czy to prawda o roxygen2? Wcześniej wspomniany post sugeruje, że użytkownik powinien zamiast tego stworzyć własną listę z elementami ze znacznikami LaTeX. Np. Nowa klasa S4, która ją rozszerza, "character"zostałaby zakodowana i udokumentowana w następujący sposób:

#' The title for my S4 class that extends \code{"character"} class.
#'
#' Some details about this class and my plans for it in the body.
#'
#' \describe{
#'    \item{myslot1}{A logical keeping track of something.}
#'
#'    \item{myslot2}{An integer specifying something else.}
#' 
#'    \item{myslot3}{A data.frame holding some data.}
#'  }
#' @name mynewclass-class
#' @rdname mynewclass-class
#' @exportClass mynewclass
setClass("mynewclass",
    representation(myslot1="logical",
        myslot2="integer",
        myslot3="data.frame"),
    contains = "character"
)

Jednak mimo to działa, to \describe, \itempodejście do dokumentowania szczelin wydaje niespójne z resztą roxygen (2), ponieważ nie istnieją żadne @-delimited tagi i szczelin może pójść nieudokumentowane bez sprzeciwu roxygenize(). Nie mówi też nic o spójnym sposobie dokumentowania dziedziczenia definiowanej klasy. Wyobrażam sobie, że zależność nadal ogólnie działa dobrze (jeśli dany boks wymaga klasy innej niż podstawowa z innego pakietu) przy użyciu @importznacznika.

Podsumowując, jaka jest obecnie najlepsza praktyka dla automatów Roxygen (2)?

Obecnie wydaje się, że należy rozważyć trzy opcje:

• A - Lista przedmiotów (jak przykład powyżej).
• B - @slot... ale brakowało mi dodatkowych tagów / implementacji. Nie mogłem zmusić @slot do pracy z roxygen / roxygen2 w wersjach, w których został on uwzględniony jako zamiennik listy wyszczególnionej w powyższym przykładzie. Ponownie powyższy przykład działa z roxygenem (2).
• C - Jakiś alternatywny tag do określania gniazd, na przykład @param, który osiągnąłby to samo.

Pożyczam / rozszerzam to pytanie z postu, który napisałem na stronie roxygen2programistycznej na github .

Zaktualizowana odpowiedź dla Roxygen2 5.0.1, aktualna od 6.0.1

W przypadku S4 najlepszą praktyką jest teraz dokumentowanie za pomocą @slotznacznika:

#' The title for my S4 class that extends \code{"character"} class.
#'
#' Some details about this class and my plans for it in the body.
#'
#' @slot myslot1 A logical keeping track of something.
#' @slot myslot2 An integer specifying something else.
#' @slot myslot3 A data.frame holding some data.
#'
#' @name mynewclass-class
#' @rdname mynewclass-class
#' @export

Z jednej strony @exportClassjest to konieczne tylko w niektórych przypadkach, @exportteraz używa się ogólnego sposobu eksportowania funkcji . Nie musisz także eksportować klasy, chyba że chcesz, aby inne pakiety mogły ją rozszerzać.

Zobacz także http://r-pkgs.had.co.nz/namespace.html#exports

Zaktualizowana odpowiedź dla Roygen2 3.0.0, aktualna od 5.0.1.

W przypadku S4 najlepszą praktyką jest dokumentacja w postaci:

#'  \section{Slots}{
#'    \describe{
#'      \item{\code{a}:}{Object of class \code{"numeric"}.}
#'      \item{\code{b}:}{Object of class \code{"character"}.}
#'    }
#'  }

Jest to zgodne z wewnętrzną reprezentacją gniazd jako listy wewnątrz obiektu. Jak zauważyłeś, ta składnia jest inna niż w innych liniach i możemy mieć nadzieję na bardziej niezawodne rozwiązanie w przyszłości, które zawiera wiedzę o dziedziczeniu - ale dzisiaj to nie istnieje.

Jak zauważył @Brian Diggs, ta funkcja została przeniesiona do 3.0.0, dalsza dyskusja na https://github.com/klutometis/roxygen/pull/85

Rozwiązanie dostarczone przez Full Decent jest OK, jeśli idziesz do dokumentowania miejsc w samych plikach Rd. Podczas używania roxygen2, można użyć tagu @sectionzrobić w zasadzie to samo z \describe. Przykład:

#' The EXAMPLE class
#'
#' This class contains an example. This line goes into the description
#'
#' This line and the next ones go into the details.
#' This line thus appears in the details as well.
#'
#'@section Slots: 
#'  \describe{
#'    \item{\code{slot1}:}{Matrix of class \code{"numeric"}, containing data from slot1}
#'    \item{\code{slot2}:}{Object of class \code{"character"}, containing data that needs to go in slot2.}
#'  }
#'
#' @note You can still add notes
#' @name EXAMPLE 
#' @rdname EXAMPLE
#' @aliases EXAMPLE-class
#' @exportClass EXAMPLE
#' @author Joris Meys

roxygen2 v4.1 + i najnowszy dokument Hadleya za zrobienie tego:

http://r-pkgs.had.co.nz/man.html#man-classes

Nie wypróbowałem go jeszcze dla RC, ale teraz działa dla mnie dla S4.

Poprzednio

Wygląda na to, że gniazda klasy S4 są w pełni obsługiwane w wersji Roxygen2 3.0+:

http://blog.rstudio.org/2013/12/09/roxygen2-3-0-0/

„udokumentować swoje klasy S4, S4 i metod klasy RC z roxygen2 - można bezpiecznie usunąć obejścia że stosowane @aliasi @usage, i po prostu polegać na roxygen2 aby zrobić dobry uczynek”.