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

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

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

在第一阶段，对于每个要缩短其名称的函数（我们称其为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")
}

So that transmute_my_carefully_crafted_data_structure_into_gold从薄薄的包装纸开始alchemy，还有一个额外的.Deprecated call.

> 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即使alchemy做;在这种情况下，您需要尽可能将旧参数映射到新参数中。

在以后的版本中，您可以更改.Deprecated to .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 更改为 package-deprecated，在描述的开头添加一行表示它已弃用，然后将新函数添加到 @seealso。当它变为 defunct 时，将 @rdname 更改为 package-defunct。