klutometis/roxygen — pull request #244 by fabian-s (2014-05-04 15:00:10+00:00)
Title: Support Markdown-syntax in Roxygen-comments

The new roclet allows you to write documentation using Markdown like this:
```
#' Testing Markdown-formatted Roxygen comments
#'
#' A link to `![t.test](stats)` in `code`-font. A link to some `![function]`
#' in the same package.
#' A displayed equation $$\log(1) = 0,$$ followed by some $\exp(0)=1$ inline math.
#'
#' A list:
#' * first item
#' 4 spaces separate the second part of item 1
#' * second item
#' An enumerated list:
#' 1. enum 1
#' * enum 2
#' 4 spaces to continue enum 2
#' 223. enum 3
#' 4. enum 4
#' Not in the enum.
#'
#' @param bar `formatted as code`
#' @return some *italic*, some **bold** text.
#' @examples
#'
#' foo("fnargl")
#'
foo <- function(bar){
return(NULL)
}
````
that get turned into this:
````
[...]
\arguments{
\item{bar}{\code{some code}}
}
\value{
some \emph{italic}, some \bold{bold} text.
}
\description{
A list:
\itemize{
\item first item
4 spaces separate the second part of item 1
\item second item }
An enumerated list:
\enumerate{
\item enum 1
\item enum 2
4 spaces to continue enum 2
\item enum 3
\item enum 4 }
Not in the enum.
}
\details{
A link to \code{\link[stats]{t.test}} in \code{code}-font. A link to some \code{\link{function}}
in the same package.
A displayed equation \deqn{\log(1) = 0,} followed by some \eqn{\exp(0)=1} inline math.
}
\examples{
foo("fnargl")
}
````

I think this
* is a subset of Rd-syntax that **covers most of what people actually use**, for anything else you can still use standard Rd-syntax as
* it is also **backwards-compatible**: Using the md2rd-roclet instead of the standard rd2-roclet should work fine for Roxygen written in standard Rd-syntax.
* **could replace the default rd-roclet** to allow us to write human-legible docs that free us from reading/typing lots of boilerplate/markup commands.

In terms of the implememtation I've tried to keep changes as limited as possible. It reuses all of the standard rd_roclet, but transforms Markdown- into Rd-syntax before doing so.

Possible downsides I anticipate are that
* the stringr/regexp based transformation might be slow for large packages ....?
* the regexps I use may fail to catch some edge cases (e.g., nested lists)

Thoughts?