41

古いパッケージを更新し、非常に長い関数名の束を短縮しています。古い関数が廃止されたことをユーザーに知らせるにはどうすればよいですか? 私はすべてを文書化しているroxygen2ので、何を使用すべきか疑問に思ってい#' @aliasますか? 考え？

4

4 に答える 4

55

関数名を短くしているだけでも、パッケージのパブリック 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")
}

そのため、追加の呼び出しを使用し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でも署名を変更しません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。

後のリリースでは、この関数を完全に削除することもできますが、道しるべとしてこの状態のままにしておきます。

roxygenを使用して使用すると述べました。deprecated への最初の移行を行うときは、@rdname を package-deprecated に変更し、説明の先頭に deprecated であることを示す行を追加し、新しい関数を @seealso に追加します。defunct に変更する場合は、@rdname を package-defunct に変更します。

于 2012-04-13T17:39:44.307 に答える
23

「正しい」答えは、あなたが望むものに依存すると思います。私の見解から：

  1. Jeff と Brandon のアプローチの問題は、インデックスに両方の関数名がリストされ、どちらが優先される名前であるかが示されないことです。さらに、ある種の .Deprecated 呼び出しがなければ、ユーザーは関数を呼び出すための好ましい方法が何であるかを知る可能性はさらに低くなります。
  2. Brian のアプローチの問題点は、複数の関数を非推奨としてリストするプロセスが明確でなかったことです。

だから、私の例を以下に入力してください。別の場所で、関数の「適切な」バージョンを定義します (例: alchemy、latinSquareDigram)。ここでは、非推奨の警告を生成したい古い「悪い」バージョンをすべて定義します。私は car パッケージのアプローチに従い、非推奨バージョンのすべての関数呼び出しを引数として ... を使用するように変更しました。これは、雑然とした @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
于 2012-12-26T05:57:14.437 に答える
4

私はしばらくの間この問題を抱えていましたが、良い解決策を見つけることができませんでした. それから私はこれを見つけました。それでも、上記の答えは、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

これで、古い関数は新しい関数の単なるコピーであるため機能し、ドキュメントはエイリアスを設定したために機能します。に含まれているため、古いバージョンもエクスポートされ@exportます。

于 2015-11-10T17:04:19.610 に答える
3

過度に長い関数名を短いバージョンに変換する場合は、両方の名前を同じ関数としてエクスポートすることをお勧めします（@Brandonのコメントを参照）。これにより、新しいユーザーに便利な代替手段を提供しながら、古いコードを引き続き機能させることができます。

私の考えでは、何かにタグを付ける唯一の理由.Deprecated（@GSEEを参照）は、機能を根本的に変更するか、将来のリリースで一部の機能のサポートを停止する予定がある場合です。この場合は、.Defunctまたはを使用できます.Deprecated。

于 2012-04-11T15:33:31.597 に答える