रॉक्सीजन 2 का उपयोग करके एस 4 क्लास स्लॉट को ठीक से कैसे दस्तावेज़ित करें?

Question

रॉक्सीजेन (2) के साथ कक्षाओं के दस्तावेजीकरण के लिए, शीर्षक और विवरण / विवरण निर्दिष्ट करना कार्यों, विधियों, डेटा, आदि के लिए समान प्रतीत होता है। हालाँकि, स्लॉट और वंशानुक्रम उनके अपने प्रकार के जानवर हैं। Roxygen2 में S4 कक्षाओं के दस्तावेजीकरण के लिए सबसे अच्छा अभ्यास क्या है - वर्तमान या योजनाबद्ध?

यथोचित परिश्रम:

मुझे @slotroxygen के शुरुआती विवरणों में एक टैग का उल्लेख मिला । 2008 R-forge मेलिंग सूची पोस्ट से प्रतीत होता है कि यह मृत है, और @slotroxygen का कोई समर्थन नहीं है :

क्या यह roxygen2 का सच है? पहले से उल्लेख की गई पोस्ट बताती है कि उपयोगकर्ता को इसके बजाय LaTeX मार्कअप के साथ अपनी आइटम सूची बनानी चाहिए। जैसे एक नया 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, वही काम पूरा करेगा।

मैं इस प्रश्न को एक पोस्ट से उधार ले रहा हूं / बढ़ा रहा हूं जिसे मैंने githubroxygen2 पर विकास पृष्ठ पर बनाया है ।

Comments

@slotशायद आप दीर्घावधि चाहते हैं, लेकिन इसे पहले लागू करना होगा ...

— हैडली

धन्यवाद! यह जानकर अच्छा लगा। मुझे खुशी है कि मेरे कोड की setClassतुलना में कई कम बयान हैं setMethod। एक बार @slotलागू होने के बाद बदलाव करना बहुत दर्दनाक नहीं होगा।

— पॉल मैकमुर्डी

@Slot पर कुछ चर्चा: github.com/klutometis/roxygen/pull/85

— ब्रायन डिग्स

संबंधित प्रश्न: stackoverflow.com/questions/13642092/…

— जोरिस मेय्स

एस 4 वर्ग अब पूरी तरह से Roxygen2 संस्करण 3 (पर उपलब्ध में समर्थित हैं GitHub )।

— ग्रेगर थॉमस

Answer 1

रॉक्सिजन 2 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

एक सिडोनेट पर, @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"}.}
#'    }
#'  }

यह ऑब्जेक्ट के अंदर एक सूची के रूप में स्लॉट्स के आंतरिक प्रतिनिधित्व के अनुरूप है। जैसा कि आप बताते हैं, यह वाक्यविन्यास अन्य लाइनों की तुलना में अलग है, और हम भविष्य में अधिक मजबूत समाधान की उम्मीद कर सकते हैं जिसमें विरासत का ज्ञान शामिल है - लेकिन आज जो मौजूद नहीं है।

जैसा कि @Brian Diggs द्वारा बताया गया है, यह फीचर 3.0.0 में लिया गया था, https://github.com/klutometis/roxygen/pull/85 पर आगे की चर्चा

Comments

क्या आपने @Brian Diggs द्वारा कार्यान्वयन का उपयोग किया है? क्या यह काम करता है? क्या आपको लगता है कि आप उस दृष्टिकोण के बारे में कुछ विवरण प्रदान कर सकते हैं (और इसलिए @slotसमाधान के लिए कुछ )। मैं इस लंबित @slotसमाधान के लिए प्रतीक्षा करने (शायद आलस्य से) इसकी कोशिश करने के लिए इधर-उधर नहीं गया । मुझे पता है कि यह सवाल कैसे खड़ा नहीं हुआ है, लेकिन टिप्पणियों (@ हैडली सहित) के आधार पर ऐसा लगता @slotहै कि यह "वास्तविक" उत्तर है। मैं आपके आकलन से सहमत हूं कि एक आइटम सूची (जैसा कि मेरे प्रश्न में है) वर्तमान सबसे अच्छा अभ्यास है, हालांकि उम्मीद है कि बहुत जल्द बदल दिया जाएगा।

— पॉल मैकमुर्डी

Answer 2

पूर्ण निर्णय द्वारा प्रदान किया गया समाधान ठीक है यदि आप Rd फाइल में स्लॉट्स के दस्तावेजीकरण के लिए जाते हैं। उपयोग करते समय 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

Answer 3

ऐसा करने के लिए roxygen2 v4.1 + और हैडली का नवीनतम डॉक:

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

मैंने आरसी के लिए अभी तक कोशिश नहीं की है, लेकिन यह मेरे लिए अभी एस 4 के लिए काम करता है।

इससे पहले

ऐसा लगता है कि एस 4 श्रेणी के स्लॉट्स को पूरी तरह से रॉक्सीजन 2 संस्करण 3.0+ के तहत समर्थित हैं:

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

"roxygen2 के साथ अपने एस 4 कक्षाएं, एस 4 तरीकों और आर सी कक्षाओं दस्तावेज़ - आप सुरक्षित रूप से समाधान का उपयोग किया जाता हटा सकते हैं @aliasऔर @usage, और बस roxygen2 पर भरोसा सही काम करने के लिए।"

Comments

@ एसएलओएल पूरी तरह से काम करता है, आप इसका उपयोग (या @ क्षेत्र) फर्जी दस्तावेज पर एक एस 3 क्लास में भी कर सकते हैं।

— ब्रैंडन बर्टेल्सन