☰

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

tag-icon • tag-icon r roxygen roxygen2
Roxygen2 - S3 メソッドを適切に文書化する方法 質問する

私はRoxygen2のPDFを読みました。サイト、@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
    }

ベストアンサー1

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
}

おすすめ記事