web-dev-qa-db-ja.com

Roxygen2-S3メソッドを適切に文書化する方法

Roxygen2 PDFおよびこれ site を読みましたが、@ method @ S3method @exportの違いと、これらを適切に使用する方法について迷っています。 S3メソッドを文書化します。議論のために次の例を作成しました。

1。これらを適切に文書化するにはどうすればよいですか？

2。すべてのクラス固有の実装のユースケースを示す？printおよびその他のジェネリック関数のドキュメントをエミュレートするにはどうすればよいですか（つまり、？printが「factor」、「table」、「function」の使用法を示す方法）

3。 wikiページから：「エクスポートされたすべてのメソッドには@ S3methodタグが必要です。これは@methodと同じ形式です。これにより、関数ではなくメソッドがエクスポートされます。つまり、generic（myobject）は機能しますが、generic.mymethod（myobject）は機能しません。 。」
これは解釈できません。これは、タグが不適切に指定されていると、関数/メソッド呼び出しが正しく機能しないことを示しているようです。具体的に何が壊れますか？

MyHappyFunction = function( x , ... )
{
    UseMethod( "MyHappyFunction" )
}

MyHappyFunction.lm = function( x , ... )
{
  # do some magic
}
rroxygenroxygen2
47
SFun28

@methodタグは、Rdファイルの\ usageフィールドに\ methodエントリを生成します。

@S3methodタグは、NAMESPACEファイルにS3method（）エントリを生成します。

@exportタグは、NAMESPACEファイルにexport（）エントリを生成します。

これが私の例です：

#' A description of MyHappyFunction
#'
#' A details of MyHappyFunction
#'
#' @title MyHappyFunction: The my happy function
#' @param x numeric number
#' @param ... other arguments
#' @examples
#' a <- 1
#' class(a) <- "lm"
#' MyHappyFunction(a)
#'
#' @rdname MyHappyFunction
#' @export MyHappyFunction
MyHappyFunction <- function(x, ...){
  UseMethod("MyHappyFunction")
}

#' @return \code{NULL}
#'
#' @rdname MyHappyFunction
#' @method MyHappyFunction lm
#' @S3method MyHappyFunction lm
MyHappyFunction.lm = function(x, ...) {
  # do some magic
}

#' @return \code{NULL}
#'
#' @rdname MyHappyFunction
#' @method MyHappyFunction default
#' @S3method MyHappyFunction default
MyHappyFunction.default = function(x, ...) {
  # do some magic
}

enter image description here

3wikiページから...

「@S3method generic mymethod myobjectを書かない」という意味だと思います。

36
Triad sou.

Roxygen2> 3.0.0の時点で、必要なのは@export：

#' A description of MyHappyFunction
#'
#' A details of MyHappyFunction
#'
#' @title MyHappyFunction: The my happy function
#' @param x numeric number
#' @param ... other arguments
#' @examples
#' a <- 1
#' class(a) <- "lm"
#' MyHappyFunction(a)
#' @export
MyHappyFunction <- function(x, ...){
  UseMethod("MyHappyFunction")
}

#' @rdname MyHappyFunction
#' @export
MyHappyFunction.lm = function(x, ...) {
  # do some magic
}

#' @rdname MyHappyFunction
#' @export
MyHappyFunction.default = function(x, ...) {
  # do some magic
}

ただし、実際にはメソッドを文書化していないため、以下で十分です。

#' A description of MyHappyFunction
#'
#' A details of MyHappyFunction
#'
#' @title MyHappyFunction: The my happy function
#' @param x numeric number
#' @param ... other arguments
#' @examples
#' a <- 1
#' class(a) <- "lm"
#' MyHappyFunction(a)
#' @export
MyHappyFunction <- function(x, ...){
  UseMethod("MyHappyFunction")
}

#' @export
MyHappyFunction.lm = function(x, ...) {
  # do some magic
}

#' @export
MyHappyFunction.default = function(x, ...) {
  # do some magic
}
58
hadley