関数から直感的にdocstringを取り出せるようにする

まずはwith_docstring関数を用意し、関数の処理の先頭が文字列なら、該当部分を関数自身の__doc__属性に保存するwith_docstring関数を定義してみましょう。ついでに、後々のことを考えてこの文字列にはdocstringクラスを与え、関数にはwith_docstringクラスを与えておきます。

これでattr(add_one, "__doc__")すればヘルプを取り出せるようになり、取り出し方が直感的になります。

with_docstring <- function(f) {
  doc <- body(f)[2L][[1L]]
  attr(f, "__doc__") <- structure(
    `if`(is.character(doc), doc, ""),
    class = "docstring"
  )
  class(f) <- c("with_docstring", class(f))
  return(f)
}

add_one <- with_docstring(.add_one)
attr(add_one, "__doc__")

## [1] "Add one.\n  \n  @param x: A numeric vector.\n  \n  @value\n  x + 1\n  "
## attr(,"class")
## [1] "docstring"

.add_one関数を定義してからadd_one関数にするのが面倒であれば、最初から関数定義をwith_docstring関数でラップしましょう。 Pythonで言うところのデコレータ的発想ですね。

add_one <- with_docstring(function(x) {
  r"---(Add one.
  
  @param x: A numeric vector.
  
  @value
  x + 1
  )---"
  x + 1
})

docstringを良い感じにprintする

docstringの抽出が簡単になりましたが、表示がイマイチです。

attr(add_one, "__doc__")

## [1] "Add one.\n  \n  @param x: A numeric vector.\n  \n  @value\n  x + 1\n  "
## attr(,"class")
## [1] "docstring"

というわけでdocstringクラス用printメソッドを実装してあげましょう。単にcatするだけでOKです。

print.docstring <- function(x, ...) {
  cat(x)
  invisible(x)
}

attr(add_one, "__doc__")

## Add one.
##   
##   @param x: A numeric vector.
##   
##   @value
##   x + 1
## 

良い感じになりましたね。

help関数をマスクする

あとはhelp関数を実装するだけです。色んな方法が考えられますが、一番シンプルな方法はhelp関数を総称関数にする手です。そして、help.with_docstringメソッドでwith_docstringクラスオブジェクトだけの専用helpを用意します。ついでにhelp.defaultを用意すれば、その他のオブジェクトに対しては従来のutils::help関数を呼べます。

以下ではhelpとhelp.with_docstring関数にたいして引数を定義せず、後からutils::help関数の引数をformals関数を使ってパクってます。このあたりについてはJapan.R 2018で発表した「関数魔改造講座 (formals編)」を参照してください。

help <- function() {
  UseMethod("help")
}
help.default <- utils::help
help.with_docstring <- function() {
  print(attr(topic, "__doc__", exact = TRUE))
}
  
formals(help) <- formals(help.with_docstring) <- formals(utils::help)
help(add_one)

## Add one.
##   
##   @param x: A numeric vector.
##   
##   @value
##   x + 1
## 

printrパッケージを使えばR Markdown内でヘルプを使えるので、docstringがない関数についてもちゃんとヘルプを呼べます。

library(printr)

## Registered S3 method overwritten by 'printr':
##   method                from     
##   knit_print.data.frame rmarkdown

help(identity)

identity(x)