r - هل هناك ممارسات أفضل/موصى بها يجب اتباعها عند إعادة تسمية الوظائف في إصدار جديد من الحزمة؟




roxygen (3)

أعتقد أن الإجابة "الصحيحة" تعتمد على ما تريد. من وجهة نظري:

  1. المشكلة في مقاربة Jeff's و Brandon هي أن الفهرس الخاص بك سوف يسرد أسماء الوظائف على حد سواء ولا يعطي أي إشارة إلى الاسم المفضل. علاوة على ذلك ، وبدون وجود نوع من المكالمة المنفصلة. من غير المرجح أن يعرف المستخدم الطريقة المفضلة لاستدعاء الوظيفة.
  2. كانت المشكلة في مقاربة برايان هي أن عملية إدراج أكثر من وظيفة على أنها مهمل كانت غير واضحة بالنسبة لي.

لذلك ، أدخل مثال بلدي أدناه. في موقع آخر ، أقوم بتحديد الإصدارات "الجيدة" من الوظائف (مثل الكيمياء ، latinSquareDigram). أعرض هنا جميع الإصدارات "السيئة" القديمة التي أريد إصدار تحذيرات إهمال لها. لقد اتبعت نهج حزمة السيارة وقمت بتغيير جميع استدعاءات الوظائف الخاصة بي لاستخدام الإصدار المهملة ... كوسيطة. لقد ساعدني ذلك في تجنب مجموعة من البياناتparam المزدحمة. لقد استخدمت أيضًا توجيهاتname و @ docType لإظهار "yourPackageName-deprecated" في الفهرس. ربما شخص ما لديه طريقة أفضل للقيام بذلك؟

الآن لا تزال كل من الوظائف المهملة تظهر في الفهرس ، لكنها تقول "وظيفة (وظائف) مهملة في حزمة yourPackageName" بجانبهم وأي مكالمات إليهم تصدر تحذيرًا بالإهمال. لإزالتها من الفهرس ، يمكن للمرء إسقاط التوجيهaliases ، ولكن بعد ذلك سيكون لديك كائنات التعليمات البرمجية غير الموثقة على مستوى المستخدم ، والتي أعتبرها ، صورة سيئة.

#' Deprecated function(s) in the yourPackageName package
#' 
#' These functions are provided for compatibility with older version of
#' the yourPackageName package.  They may eventually be completely
#' removed.
#' @rdname yourPackageName-deprecated
#' @name yourPackageName-deprecated
#' @param ... Parameters to be passed to the modern version of the function
#' @docType package
#' @export  latinsquare.digram Conv3Dto2D Conv2Dto3D dist3D.l
#' @aliases latinsquare.digram Conv3Dto2D Conv2Dto3D dist3D.l
#' @section Details:
#' \tabular{rl}{
#'   \code{latinsquare.digram} \tab now a synonym for \code{\link{latinSquareDigram}}\cr
#'   \code{Conv3Dto2D} \tab now a synonym for \code{\link{conv3Dto2D}}\cr
#'   \code{Conv2Dto3D} \tab now a synonym for \code{\link{conv2Dto3D}}\cr
#'   \code{dist3D.l} \tab now a synonym for \code{\link{dist3D}}\cr
#' }
#'  
latinsquare.digram <- function(...) {
  .Deprecated("latinSquareDigram",package="yourPackageName")
  latinSquareDigram(...)
}
Conv3Dto2D <- function(...) {
  .Deprecated("conv3Dto2D",package="yourPackageName")
  conv3Dto2D(...)
}
Conv2Dto3D <- function(...) {
  .Deprecated("conv2Dto3D",package="yourPackageName")
  conv2Dto3D(...)
}
dist3D.l <- function(...) {
  .Deprecated("dist3D",package="yourPackageName")
  dist3D(...)
}
NULL

أقوم بتحديث حزمة قديمة وتقصير مجموعة من أسماء الوظائف الطويلة حقًا. كيف يمكنني إعلام المستخدم بالوظيفة القديمة التي تم إهمالها؟ أقوم بتوثيق كل شيء باستخدام roxygen2 لذلك أتساءل عما إذا كان #' @alias هو ما يجب استخدامه؟ أفكار؟


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

في المرحلة الأولى ، لكل وظيفة تريد اختصار اسمها (دعنا نسميها transmute_my_carefully_crafted_data_structure_into_gold ) ، يمكنك الاحتفاظ بوظيفة مع هذا التوقيع ، لكن بنقل كل الكود الفعلي إلى وظيفتك المسماة حديثًا (دعنا نسميها alchemy ).

في البداية:

transmute_my_carefully_crafted_data_structure_into_gold <- function(lead, alpha=NULL, beta=3) {
  # TODO: figure out how to create gold
  # look like we are doing something
  Sys.sleep(10)
  return("gold")
}

الإصدار الأول بأسماء جديدة:

transmute_my_carefully_crafted_data_structure_into_gold <- function(lead, alpha=NULL, beta=3) {
  .Deprecated("alchemy") #include a package argument, too
  alchemy(lead=lead, alpha=alpha, beta=beta)
}

alchemy <- function(lead, alpha=NULL, beta=3) {
  # TODO: figure out how to create gold
  # look like we are doing something
  Sys.sleep(10)
  return("gold")
}

بحيث يبدأ transmute_my_carefully_crafted_data_structure_into_gold كملف نحيف حول alchemy ، مع مكالمة إضافية .Deprecated .

> transmute_my_carefully_crafted_data_structure_into_gold()
[1] "gold"
Warning message:
'transmute_my_carefully_crafted_data_structure_into_gold' is deprecated.
Use 'alchemy' instead.
See help("Deprecated") 
> alchemy()
[1] "gold"

إذا قمت بإجراء تغييرات على alchemy ، فلا يزال يتم transmute_my_carefully_crafted_data_structure_into_gold بواسطة transmute_my_carefully_crafted_data_structure_into_gold حيث أن ذلك يستدعي السابق فقط. ومع ذلك ، لا يمكنك تغيير توقيع transmute_my_carefully_crafted_data_structure_into_gold حتى لو لم تتغير alchemy ؛ في هذه الحالة ، يلزمك تعيين الحجج القديمة في الوسيطات الجديدة قدر الإمكان.

في إصدار لاحق ، يمكنك تغيير .Deprecated إلى .Defunct .

> transmute_my_carefully_crafted_data_structure_into_gold()
Error: 'transmute_my_carefully_crafted_data_structure_into_gold' is defunct.
Use 'alchemy' instead.
See help("Defunct")

لاحظ أن هذا خطأ ويتوقف ؛ أنها لا تمضي قدما واستدعاء alchemy .

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

لقد ذكرت باستخدام استخدام الأوكسجين. عندما تقوم بإجراء النقل الأول للإهمال ، يمكنك تغييرrdname إلى إهمال الحزمة ، إضافة سطر في بداية الوصف يقول أنه تم إهماله ، أضف الوظيفة الجديدة إلىseealso. عندما يتغير إلى defunct ، قم بتغييرrdname إلى الحزمة defunct.


لقد واجهت هذه المشكلة لبعض الوقت ولم أتمكن من إيجاد حل جيد. ثم وجدت هذا. ومع ذلك ، فإن الإجابات أعلاه معقدة للغاية بالنسبة للحالة البسيطة حيث يريد المرء فقط: 1) إضافة اسم مستعار بحيث لا يتوقف الرمز القديم عن العمل ، 2) يجب أن يعمل الاسم المستعار مع الوثائق المضمنة ، و 3) ينبغي القيام به مع roxygen2.

أولاً ، أضف نسخة من الوظيفة:

old_function_name = new_function_name

ثم ، حيث يتم تعريف new_function_name () ، أضف إلى roxygen2:

#' @export new_function_name old_function_name
#' @aliases old_function_name

تعمل الوظيفة القديمة الآن لأنها مجرد نسخة من الوظيفة الجديدة ، وتعمل الوثائق لأنك تقوم بإعداد الاسم المستعار. يتم تصدير الإصدار القديم أيضًا لأنه مضمن في التصدير.







roxygen