وظائف متعددة في ملف.Rd واحد




documentation package (2)

نسخة مختصرة : هل يمكنني محاكاة وثائق " Normal في stats الحزمة باستخدام roxygen ؟

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

أخذت إلهامًا للوثائق الخاصة بـ Normal والتي توفر عددًا من الطرق المتعلقة بالتوزيع العادي ، على سبيل المثال stats::dnorm() .

عندما أقوم بالبحث ?dnorm أجد أن اسم قسم المساعدة " Normal على الرغم من أن " Normal لا يبدو أنه دالة أو كائن تم تصديره.

ما جربته هو وضع ما يلي في funs.R :

##' @rdname funs
##' @name funs
##' @aliases sum1
##' @aliases prod1
##' @title Two functions
##' @param x X
##' @param y Y
##' @return sum1 returns x+y
##' \cr
##' prod1 returns x*y
##' @examples
##' sum1(3,4)
##' prod1(3,4)
##' @export
sum1 <- function(x,y) x+y
##' @export
##' @rdname funs
prod1 <- function(x,y) x*y

أنا ثم تشغيل roxygen2 على ما سبق. تكمن الصعوبة في أنه عند تشغيل R CMD check على هذه الحزمة البسيطة ، فإنها تجد أن الحزمة لا يمكن تحميلها undefined exports: funs . إذا قمت بإزالة السطر ##' @name funs الحزمة إلى R CMD check ولكن اسم قسم المساعدة هو sum1 بدلاً من funs . إذا أضفت ما يلي أدناه قسم الأمثلة:

##' @export
funs <- function(x) x

لقد مررت وأستطيع أن أرى المساعدة مهيأة كما أريد ، لكنني أصدّر وظيفة لا معنى لها من أجل الحصول على الاسم لعرضه بشكل صحيح.

حاولت البحث في ملفات التعليمات المصدر للحصول على stats لمعرفة كيف تم تحقيق ذلك ، لكنها بتنسيق .Rdx الذي لست متأكدًا من طريقة عرضه.

أيضًا ، في ملاحظة ذات صلة ، هل أي نوع من الأشياء Normal ؟

require(stats)
getAnywhere("Normal")
> no object named 'Normal' was found

تحديث:

TylerRinker - أخشى أن هذا هو أول شيء جربته. يجمع هذا بين الوظائف في ملف .Rd واحد ولكن اسم المساعدة المرتبطة هو نفس اسم الوظيفة الأولى ، وهو ما كنت أحاول تجنبه:

##' sum
##' gives the sum
##' @param x X
##' @param y Y
##' @return sum1 returns x+y
##' @examples
##' sum1(3,4)
##' @rdname funs
##' @export
sum1 <- function(x,y) x+y
##' product
##' gives the product
##' @return prod1 returns x*y
##' @examples
##' prod1(3,4)
##' @rdname funs
##' @export
prod1 <- function(x,y) x*y

Andrie - هذا الحل يسبب نفس الصعوبة تمامًا ، اسم المساعدة هو نفس الوظيفة الأولى.

ربما هذا غير ممكن ...


بقدر ما أفهم ، فإن الطريقة الوحيدة للحصول على 3 أسماء موثقة في ملفك .Rd هي توثيق 3 كائنات فعلية كما فعلت. ولكن الحيلة هي: واحد منهم يمكن أن يكون بلا قيمة ولا يتم تصديره!

##' @name funs
##' @rdname funs
##'
##' @title Two functions of sum1 and prod1
##'
##' @param x =X
##' @param y =Y
##'
##' @return x*y (prod1) or x+y (sum1).
NULL

##' @rdname funs
##' @examples
##' sum1(3,4)
##' @export
sum1 <- function(x,y) x+y

##' @rdname funs
##' @examples
##' prod1(3,4)
##' @export
prod1 <- function(x,y) x*y

يبدو خارقة جدا ، لكنه يعمل.


هذا هو الحل الأفضل الذي وجدته ، ولكن سيكون من دواعي سروري تغيير الإجابة المقبولة إذا جاء شيء أفضل ...

##' @name funs
##' @aliases sum1
##' @aliases prod1
##'
##' @title Two functions of x and y
##'
##' @param x =X
##' @param y =Y
##'
##' @note \code{funs} is a generic name for the functions documented.
##' \cr
##' If called, \code{funs} returns its own arguments.
##'
##' @rdname funs
##' @export
funs <- function(x,y) {identity(c(x,y))}
##'
##' @rdname funs
##' @return \code{sum1(x,y)} returns x+y
##' @examples
##' sum1(3,4)
##' @export
sum1 <- function(x,y) x+y
##'
##' @rdname funs
##' @return \code{prod1(x,y)} returns x*y
##' @examples
##' prod1(3,4)
##' @export
prod1 <- function(x,y) x*y

لاحظ أن التنسيق يتجنب استخدام @usage لتجنب جعل هذا خطأ يمكن الإبلاغ عنه .

أستطيع أن أرى كيف يمكن معالجة ذلك بشكل أفضل على github .

الحل الأفضل الذي يستخدم @usage هو إضافة السطر التالي:

##' @usage funs(x,y) A nominal function of x and y

بعد أول استخدام ل

##' @rdname funs
##' @export

ومع ذلك أحاول تقليل لا. من التحذيرات التي R CMD check أجل استرضاء الصلاحيات التي تكون ، ولا سيما folloiwng:

 Functions with \usage entries need to have the appropriate \alias
    entries, and all their arguments documented.
    The \usage entries must correspond to syntactically valid R code.

قد يكون هذا الأخير خطأً في قراءتي للوثائق الخاصة بـ @usage .

شكرا جزيلا.







roxygen2