Use Markdown for function documentation?

[peterdesmet]

I didn't know this, but you can use Markdown in addition to Roxygen syntax for function document: http://klutometis.github.io/roxygen/articles/markdown.html, by adding to DESCRIPTION:

Roxygen: list(markdown = TRUE)

It would allow for less verbose documentation, e.g.:

#' Plot a vertical profile (`vp`)
#'
#' @param x A `vp` class object.
#' @param quantity Character string with the quantity to plot. See
#' \link[=summary.vp]{vp} for list of available quantities.
#' - Aerial density related: `dens`, `eta`, `dbz`, `DBZH` for density,
#' reflectivity, reflectivity factor and total reflectivity factor,
#' respectively.
#' - Ground speed related: `ff` ,`dd`, for ground speed and direction,
#' respectively.
#' @param xlab A title for the x axis.
#' @param ylab A title for the y axis.
#' @param line_col Color of the plotted curve.
#' @param line_lwd Line width of the plotted curve.
#' @param ... Additional arguments to be passed to the low level
#' \link[graphics]{plot} plotting function.
#' @param line.col Deprecated argument, use line_col instead.
#' @param line.lwd Deprecated argument, use line_lwd instead.

Instead of the current:

https://github.com/adokter/bioRad/blob/9c277cbed7aaf382046e83f9d111836d532a3feb/R/plot.vp.R#L1-L20

More or less getting rid of all the \something{text} which is easier to write and read. We could tackle this on a function by function basis if we update these.

[peterdesmet]

See also:

• Regular Roxygen documentation guidelines: http://r-pkgs.had.co.nz/man.html
• Tidyverse Roxygen documentation guidelines: https://style.tidyverse.org/documentation.html

[peterdesmet]

One change is e.g. \link[ggmap]{get_map} to \code{ggmap::get_map()} (does not require Markdown enabled).

[peterdesmet]

I plan to set this up tomorrow.

[PietrH]

@peterdesmet Can this be closed as completed in #558 and #564 ?

[peterdesmet]

Yes.