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 @slot
wczesnych 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 @slot
roxygen:
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
, \item
podejś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 @import
znacznika.
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 roxygen2
programistycznej na github .
@slot
jest prawdopodobnie tym, czego chcesz na dłuższą metę, ale najpierw trzeba go wdrożyć ...setClass
instrukcji niżsetMethod
. Dokonanie zmiany po jej@slot
wdrożeniu nie będzie zbyt bolesne.Odpowiedzi:
Zaktualizowana odpowiedź dla Roxygen2 5.0.1, aktualna od 6.0.1
W przypadku S4 najlepszą praktyką jest teraz dokumentowanie za pomocą
@slot
znacznika:Z jednej strony
@exportClass
jest to konieczne tylko w niektórych przypadkach,@export
teraz 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:
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
źródło
@slot
rozwiązania). Nie próbowałem tego, czekając (być może leniwie) na to oczekujące@slot
rozwiązanie. Wiem, że pytanie nie jest takie, ale na podstawie komentarzy (w tym @ hadley) wydaje się, że@slot
jest to „prawdziwa” odpowiedź. Zgadzam się z twoją oceną, że wyszczególniona lista (jak w moim pytaniu) jest obecnie najlepszą praktyką, ale mam nadzieję, że wkrótce zostanie zastąpiona.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@section
zrobić w zasadzie to samo z\describe
. Przykład:źródło
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
@alias
i@usage
, i po prostu polegać na roxygen2 aby zrobić dobry uczynek”.źródło