6

狙って撃つ前に

この質問はこの投稿と密接に関連していることを私は知っています。実際、私はさまざまな回答で与えられたアドバイスに従いましたが、結果のヘルプファイルは少し「ぎこちない」か、少なくとも少し「まとまって」いるように感じます。したがって、私の質問です。

実際の質問

  1. S4ジェネリックとそれぞれのメソッドをドキュメント化する場合、ユーザーがさまざまなメソッドを明確に区別できるRdファイル構造を作成して、ドキュメントのどの部分が特定のメソッドに属しているかを明確にするにはどうすればよいですか？
  2. タグを提供した場合、特定のメソッド@aliasのヘルプを取得しようとするときに実際にタグを使用するにはどうすればよいですか？ただタイプする代わりに何か？?foo-character-method?foo
  3. 各メソッドにはそれぞれのドキュメントが確実に含まれるため、a）ジェネリックメソッドの署名引数をまったくドキュメント化しない方がよいでしょう。b）これもそれぞれのメソッド次第であるため、戻り値はありますか？

今のところ、少なくとも視覚的には、一般的な方法とさまざまな方法の適切な区別を実際には処理できないように見えるヘルプファイルになってしまったように感じます。

しかし、多分私はまだこれを完全に取得していません;-)。この場合、どんなポインタでも大歓迎です！

mypkgこれは、S4ジェネリックと2つのメソッドを含むパッケージを生成する再現可能な例です。私はこの投稿とWritingRExtensionsで与えられたアドバイスに従おうとしました

ディレクトリの確保

sapply(c("src", "package"), dir.create, showWarnings=FALSE)

ジェネリックメソッドの定義

gnrc.roxy <- c(
    "#' Doing Something Useful",
    "#'", 
    "#' Description here.",
    "#'", 
    "#' @param x A signature argument for method dispatch.",
    "#' @param y A signature argument for method dispatch.",
    "#' @param arg.1 A \\code{logical} scalar. If \\code{TRUE} (default)", 
    "#'      something happens; else not.",
    "#' @param arg.2 A \\code{numeric} vector containing some useful numbers.", 
    "#' @param ... Further arguments.",
    "#' @return Depends on the actual method.", 
    "#' @references \\url{http://www.rappster.de/}",
    "#' @author Janko Thyson \\email{janko.thyson@@rappster.de}",
    "#' @examples", 
    "#'   foo(x=\"a\", y=letters[1:5])",
    "#'   foo(x=\"a\", y=1:5)",
    "#' @docType methods",
    "#' @rdname foo-methods",
    "#' @export"
)    
gnrc.def <- c(
    "setGeneric(",
    "    name=\"foo\",",
    "    signature=c(\"x\", \"y\"),",
    "    def=function(",
            "x,",
            "y,",
            "arg.1=TRUE,",
            "arg.2,",
            "...",
    ") {",
    "standardGeneric(\"foo\")",       
    "})"
)
path <- "src/gnrc_foo.R"
write(gnrc.roxy, file=path)
write(gnrc.def, file=path, append=TRUE)

関連するメソッドの定義

mthd1.roxy <- c(
    "#' @param x A \\code{character} scalar.",
    "#' @param y A \\code{character} vector.",
    "#' @return A \\code{character} vector.", 
    "#' @docType methods",
    "#' @rdname foo-methods",
    "#' @rdname foo-methods",
    "#' @aliases foo,character,character-method",
    "#' @export"
)    
mthd1.def <- c(
    "setMethod(",
        "f=\"foo\",",
        "signature=signature(x=\"character\", y=\"character\"),", 
        "definition=function(",
            "x,",
            "y,", 
            "...",
        ") {",
        "print(x);print(y);return(y)",
        "})"
)    
path <- "src/mthds_foo.R"
write(mthd1.roxy, file=path)
write(mthd1.def, file=path, append=TRUE)

mthd2.roxy <- c(
    "#' @param x A \\code{character} scalar.",
    "#' @param y A \\code{numeric} vector.",
    "#' @return A \\code{numeric} vector.", 
    "#' @docType methods",
    "#' @rdname foo-methods",
    "#' @rdname foo-methods",
    "#' @aliases foo,character,numeric-method",
    "#' @export"
)    
mthd2.def <- c(
    "setMethod(",
        "f=\"foo\",",
        "signature=signature(x=\"character\", y=\"numeric\"),", 
        "definition=function(",
            "x,",
            "y,", 
            "...",
        ") {",
        "print(x);print(y);return(y)",
        "})"
)    
write(mthd2.roxy, file=path, append=TRUE)
write(mthd2.def, file=path, append=TRUE)

# Test source to see if methods were defined correctly
#sapply(list.files("src", full.names=TRUE), source)

パッケージスケルトンを作成する

# Ensure empty package directory
subdirs <- list.files("package", full.names=TRUE)
if (length(subdirs)) {
    sapply(subdirs, unlink, recursive=TRUE)
}

pkg.name    <- "mypkg"
path        <- file.path("package", pkg.name)

package.skeleton(
    name=pkg.name, 
    path="package", 
    code_files=list.files("src", full.names=TRUE, recursive=TRUE)
)

酸素化

require("roxygen2")
roxygenize(package.dir=path)

Rdファイルにパッチを適用する

Rdファイルの手動編集など、手動による介入を必要としない自動チェックおよびビルドプロセスを可能にするために、パッチを適用する必要があるものもあります。

rdfiles <- list.files(file.path(path, "man"), full.names=TRUE)

# 1) Removing unnecessary file './package/mypgk/man/foo.Rd'
file <- grep("foo.Rd", rdfiles, value=TRUE)
if (length(file)) {
    unlink(file)
}

# 2) Patching './mypkg/man/mypkg-package.Rd' to pass R CMD CHECK
file <- grep(paste(pkg.name, "-package.Rd", sep=""), rdfiles, value=TRUE)
if (length(file)) {
    cnt <- readLines(file, warn=FALSE)
    idx.0 <- grep("\\\\examples\\{", cnt)
    if (length(idx.0)) {
        idx.1 <- grep("\\}", cnt)
        idx.1 <- max(idx.1[which(idx.1 > idx.0)])
        exnew <- c(
            "\\examples{",
            "# TODO: add examples",
            "}"
        )
        cnt <- cnt[-(idx.0:idx.1)]
        cnt <- append(cnt, exnew, after=idx.0-1)
        write(cnt, file=file)
    }
}

パッケージを確認してください

shell(paste("R CMD check", path), intern=FALSE)

パッケージをビルドしてインストールします

shell(paste("R CMD INSTALL",  path), intern=FALSE)

ヘルプファイルを調査します

require("mypkg")

foo(x="a", y=letters)
foo(x="a", y=1:10)

?foo

別の方法：ビルドとインストールの分離

shell(paste("R CMD INSTALL --build --data-compress=gzip ",  path), intern=FALSE)

install.packages(paste0(pkg.name, "_1.0.zip"), type="win.binary")

require("mypkg")

?foo
4

0 に答える 0