Oksijenli sınıfları belgelemek için (2), bir başlık ve açıklama / ayrıntı belirtmek işlevler, yöntemler, veriler vb. İle aynı görünmektedir. Ancak, yuvalar ve kalıtım kendi hayvan türleridir. Oksijen2'deki S4 sınıflarını belgelemek için mevcut veya planlanmış en iyi uygulama nedir?

Durum tespit süreci:

@slotOksijenin erken tanımlarında bir etiketten bahsetmiştim . 2008 R-forge posta listesi gönderisi bunun öldüğünü gösteriyor ve @slotoksijeni desteklemiyor :

Bu roxygen2 için doğru mu? Daha önce bahsedilen gönderi, kullanıcının bunun yerine LaTeX işaretlemesiyle kendi ayrıntılı listesini yapması gerektiğini önermektedir. Örneğin, "character"sınıfı genişleten yeni bir S4 sınıfı şu şekilde kodlanır ve belgelenir:

#' 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"
)

Bununla birlikte, bu işe yarıyor olsa da, bu \describe, \itemyuvaları belgeleme yaklaşımı, geri kalan hiç bir @etiket bulunmaması ve yuvaların itiraz olmadan belgelenemeyeceği için , geri kalan oksijen ile (2) tutarsız görünmektedir roxygenize(). Ayrıca, tanımlanan sınıfın mirasını belgelemenin tutarlı bir yolu hakkında hiçbir şey söylemez. Bağımlılığı hala (belirli bir yuva başka bir paketten temel olmayan bir sınıf gerektiriyorsa) genellikle iyi çalışıyor hayal ediyorum @import.

Özetlemek gerekirse, oksijen (2) yuvaları için en iyi uygulama hangisidir?

Şu anda dikkate alınması gereken üç seçenek var:

• A - Ayrıntılı liste (yukarıdaki örnekte olduğu gibi).
• B - @slot... ama ekstra etiketler / uygulama ile kaçırdım. Yukarıdaki örnekte listelenen listenin yerini alan sürümlerde roxygen / roxygen2 ile çalışmak için @slot alamadım. Yine, yukarıdaki örnek, oksijen ile çalışmaktadır (2).
• C - Yuvaları belirtmek @paramiçin aynı şeyi başaracak alternatif bir etiket .

Bu soruyu github'dakiroxygen2 geliştirme sayfasına yaptığım bir yazıdan ödünç alıyorum / genişletiyorum .

6.0.1'den beri geçerli olan Roxygen2 5.0.1 için güncellenmiş cevap

S4 için, şimdi en iyi uygulama şu @slotetiketi kullanarak belgelendirmektir :

#' 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

Bir sidenote üzerinde @exportClass, sadece bazı durumlarda, bir işlevi dışa aktarmanın genel yolu @exportşimdi kullanmaktır . Başka paketlerin sınıfı genişletmesini istemiyorsanız, bir sınıfı dışa aktarmanız da gerekmez.

Ayrıca bkz. Http://r-pkgs.had.co.nz/namespace.html#exports

5.0.1'den beri geçerli olan Roygen2 3.0.0 için cevap güncellendi.

S4 için en iyi uygulama formdaki belgelerdir:

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

Bu, nesnelerin içindeki bir liste olarak yuvaların dahili gösterimi ile tutarlıdır. Belirttiğiniz gibi, bu sözdizimi diğer satırlardan farklıdır ve gelecekte miras bilgisini içeren daha sağlam bir çözüm umuyoruz - ama bugün mevcut değil.

@Brian Diggs tarafından işaret edildiği gibi, bu özellik 3.0.0'a çekildi, daha fazla tartışma için https://github.com/klutometis/roxygen/pull/85

Rd dosyalarındaki yuvaları belgelemeye giderseniz, Full Decent tarafından sağlanan çözüm tamamdır. Kullanırken roxygen2, etiketi @sectiontemelde aynısını yapmak için kullanabilirsiniz \describe. Bir örnek:

#' 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 + ve Hadley'in bunu yapmak için en son dokümanı:

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

RC için henüz denemedim, ama şimdi S4 için çalışıyor.

Önceden

S4 sınıfı yuvalar Roxygen2 sürüm 3.0+ altında tam olarak destekleniyor gibi görünüyor:

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

"roxygen2 ile S4 sınıfları, S4 yöntem ve RC sınıfları belge - güvenle kullanılan geçici çözümler kaldırabilir @aliasve @usageve sadece doğru olanı yapmak için roxygen2 güvenir."