كيفية توثيق طريقة S3 بشكل عام من حزمة مختلفة ، باستخدام Roxygen؟




(2)

تحديث

اعتبارًا من roxygen2> 3.0.0 ، أصبحت الحزمة أكثر ذكاءً في معرفة كل هذا من أجلك. أنت الآن بحاجة فقط إلى علامة export وسيعمل الأكسجين على تحديد نوع الشيء الذي تقوم NAMESPACE والقيام بالشيء المناسب عند كتابة NAMESPACE وما إلى ذلك أثناء التحويل.

هناك استثناءات حيث قد تحتاج إلى مساعدة من الأكسجين . example يستخدمه هادلي ويكهام في كتابه R Packages هو all.equal.data.frame . يوجد غموض في اسم الوظيفة هذا فيما يتعلق بما هو الفئة وما هي الوظيفة العامة ( all ، all.equal ، أو all.equal.data

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

@method all.equal data.frame

تشرح الإجابة الأصلية أدناه المزيد حول السلوك الأقدم إذا كنت بحاجة إلى استخدام @method بشكل صريح.

أصلي

يجب توثيق الوظيفة مع علامة @method :

#' @method print surveyor

في القراءة الأولية ، كانت وثيقة @ hadley مربكة بعض الشيء بالنسبة لي لأنني لست معتادًا على الأكسجين ، لكن بعد عدة قراءات في هذا القسم ، أعتقد أنني أفهم سبب @method إلى @method .

أنت تكتب الوثائق الكاملة لطريقة print . @S3method بـ NAMESPACE ويرتب طريقة تصديرها. لا يقصد @S3method لتوثيق الطريقة.

يجب أن يحتوي ملف Rd على ما يلي في قسم usage :

\method{print}{surveyor}(x, ...)

إذا كان هذا يعمل بشكل صحيح ، فهذه هي الطريقة الصحيحة لتوثيق أساليب S3 في ملفات Rd.

أكتب حزمة تُعرّف فئة جديدة print.surveyor وطريقة print لهذا الغرض ، أي print.surveyor . يعمل الرمز الخاص بي بشكل جيد وأنا أستخدم roxygen للتوثيق المضمن. لكن R CMD check يصدر تحذيرًا:

وظائف / طرق الاستخدام في كائن التوثيق "print.surveyor" ولكن ليس في الكود: print

لقد استخدمت الصفحتين التاليتين ، الذي كتبه هادلي ، كمصدر إلهام: Namespaces ووظائف التوثيق ، وكلاهما ينص على أن بناء الجملة الصحيح هو @method function-name class

لذلك سؤالي هو: ما هي الطريقة الصحيحة لتوثيق طريقة print لفصلتي الجديدة باستخدام Roxygen؟ وبشكل أكثر تحديداً ، كيف أتخلص من التحذير؟

إليك الرمز الخاص بي: (أشارت الوثائق المعلقة إلى محاولات لإصلاح هذا الأمر ، ولم ينجح أي منها.)

#' Prints surveyor object.
#' 
#' Prints surveyor object
#' 
## #' @usage print(x, ...)
## #' @aliases print print.surveyor
#' @param x surveyor object
#' @param ... ignored
#' @S3method print surveyor
print.surveyor <- function(x, ...){
    cat("Surveyor\n\n")
    print.listof(x)
}

والمخرجات المؤكسدة ، أي print.surveyor.Rd :

\name{print.surveyor}
\title{Prints surveyor object.}
\usage{print(x, ...)
#'}
\description{Prints surveyor object.}
\details{Prints surveyor object

#'}
\alias{print}
\alias{print.surveyor}
\arguments{\item{x}{surveyor object}
\item{...}{ignored}}

اعتبارًا من roxygen2> 3.0.0 ، ستحتاج فقط إلى @export لأن الأكسجين يمكنه اكتشاف أن print.surveyor هي طريقة S3. هذا يعني أنك تحتاج الآن فقط

#' Prints surveyor object.
#' 
#' @param x surveyor object
#' @param ... ignored
#' @export
print.surveyor <- function(x, ...){
    cat("Surveyor\n\n")
    print.listof(x)
}

ومع ذلك ، في هذه الحالة ، نظرًا لأن الوثائق ليست مفيدة للغاية ، فمن الأفضل القيام بما يلي:

#' @export
print.surveyor <- function(x, ...){
    cat("Surveyor\n\n")
    print.listof(x)
}




roxygen