كيفية بشكل صحيح وثيقة S4 الدرجة فتحات باستخدام Roxygen2?

Question

لتوثيق الطبقات مع roxygen(2), تحديد العنوان و الوصف/التفاصيل يبدو أن نفس الوظائف وأساليب البيانات ، إلخ.ومع ذلك, فتحات الميراث هي نوع الخاصة بهم من الحيوان.ما هي أفضل الممارسات -- الحالية أو المخطط لها-على توثيق S4 دروس في roxygen2?

العناية الواجبة:

وجدت ذكر @slot الوسم في وقت مبكر أوصاف roxygen.2008 R-إقامة القائمة البريدية البريد ويبدو أن تشير إلى أن هذا هو الميت ، و لا يوجد أي دعم @slot في roxygen:

هل هذا صحيح من roxygen2?سبق-ذكرت آخر يشير إلى المستخدم بدلا من ذلك جعل الخاصة بهم قائمة مفصلة مع اللاتكس العلامات.E. g.جديد S4 الطبقة التي تمتد "character" الفئة ستكون مشفرة و توثيق مثل هذا:

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

ومع ذلك ، على الرغم من أن يعمل هذا ، \describe , \item نهج توثيق فتحات تبدو غير متناسقة مع بقية roxygen(2) في أنه لا توجد @-محدد العلامات فتحات يمكن أن تذهب غير الشرعيين دون أي اعتراض من roxygenize().كما يقول شيئا عن ثابت طريقة لتوثيق الإرث من الطبقة يجري تعريفها.أتصور أن التبعية لا تزال عموما يعمل بشكل جيد (إذا كان معين فتحة يتطلب عدم الفئة الأساسية من حزمة أخرى) باستخدام @import الوسم.

لذا لتلخيص ما هي أفضل الممارسات من أجل roxygen(2) فتحات ؟

يبدو أن هناك ثلاثة خيارات النظر في هذه اللحظة:

• أ-قائمة مفصلة (كما في المثال أعلاه).
• ب - @slot ...ولكن مع علامات اضافية/تنفيذ فاتني.كنت غير قادر على الحصول على @فتحة للعمل مع roxygen / roxygen2 في الإصدارات حيث أدرج كبديل قائمة مفصلة في المثال المذكورة أعلاه.مرة أخرى, على سبيل المثال أعلاه لا تعمل مع roxygen(2).
• ج-بعض بديلة الوسم لتحديد فتحات مثل @param, ، التي من شأنها أن تفعل نفس الشيء.

أنا الاقتراض/تمديد هذا السؤال من خلال وظيفة صنعت إلى roxygen2 تطوير صفحة على جيثب.

Answer 1

roxygen2 v4.1+ و هادلي أحدث دكتور على هذا:

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

أنا لم أحاول حتى الآن عن الصليب الأحمر, ولكن بالنسبة لي كان يعمل على S4 الآن.

سابقا

يبدو S4 الدرجة فتحات معتمدة بشكل كامل تحت Roxygen2 الإصدار 3.0+:

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

"الوثيقة الخاصة بك S4 دروس S4 أساليب RC الطبقات مع roxygen2 – يمكنك بأمان إزالة الحلول التي تستخدم @alias و @usage, و تعتمد ببساطة على roxygen2 أن تفعل الشيء الصحيح."

Answer 2

تحديث الإجابة عن Roxygen2 5.0.1 اعتبارا من 6.0.1

ل S4 أفضل ممارسة الآن هو توثيق استخدام @slot العلامة:

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

على sidenote ، @exportClass هو ضروري فقط في بعض الحالات ، طريقة لتصدير الدالة باستخدام @export الآن.أنت أيضا لم يكن لديك إلى تصدير فئة, إلا إذا كنت تريد الحزم الأخرى أن تكون قادرة على توسيع الطبقة.

انظر أيضا http://r-pkgs.had.co.nz/namespace.html#exports

تحديث الإجابة عن Roygen2 3.0.0 اعتبارا من 5.0.1.

ل S4 هو أفضل ممارسة الوثائق في شكل:

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

وهذا يتفق مع التمثيل الداخلي فتحات قائمة داخل الكائن.كما تشير هذه الجملة مختلفة من خطوط أخرى ، وقد الأمل في الحل أكثر قوة في المستقبل الذي يشتمل على المعرفة من الميراث لكن اليوم غير موجود.

كما أشار @براين تايلور هذه الميزة تم سحبها في 3.0.0, مزيد من المناقشة في https://github.com/klutometis/roxygen/pull/85

Answer 3

قدمت الحل الكامل اللائق هو موافق إذا ذهبت لتوثيق فتحات في طريق الملفات نفسها.عند استخدام roxygen2, يمكنك استخدام الوسم @section للقيام الأساس نفسه مع \describe.على سبيل المثال:

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