r - 在新版本的包中重命名函数时，是否有最佳/推荐的做法可以遵循？

Question

我正在更新一个旧包并缩短一堆非常长的函数名称。如何让用户知道旧功能已被弃用？我用 roxygen2 记录所有内容，所以我想知道 #' @alias 是否是我应该使用的？想法？

Answer 1

即使您只是缩短函数名称，我仍然会像对包的公共(public) API 进行任何更改一样对待它:随着新函数的引入，对旧函数进行弃用/失效阶段。

在第一阶段，对于每个要缩短名称的函数(我们称之为 transmute_my_careously_crafted_data_struction_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_careously_crafted_data_struct_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_careously_crafted_data_struct_into_gold 携带，因为它只调用前者。但是，即使 alchemy 更改了 transmute_my_careously_crafted_data_struction_into_gold 的签名，您也不​​会更改它；在这种情况下，您需要尽可能将旧参数映射到新参数中。

在更高版本中，您可以将 .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。

您可以在以后的版本中完全删除此函数，但我会将其保留为这种状态作为路标。

您提到使用 roxygen。当您第一次转换为已弃用时，您可以将 @rdname 更改为 package-deprecated，在描述的开头添加一行表示它已弃用，然后将新函数添加到 @seealso。当它变为 defunct 时，将 @rdname 更改为 package-defunct。