(window.webpackJsonp=window.webpackJsonp||[]).push([[2951],{3359:function(t,e,a){"use strict";a.r(e);var n=a(31),o=Object(n.a)({},(function(){var t=this,e=t.$createElement,a=t._self._c||e;return a("ContentSlotsDistributor",{attrs:{"slot-key":t.$parent.slotKey}},[a("h1",{attrs:{id:"roxygen2"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#roxygen2"}},[t._v("#")]),t._v(" roxygen2")]),t._v(" "),a("h2",{attrs:{id:"documenting-a-package-with-roxygen2"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#documenting-a-package-with-roxygen2"}},[t._v("#")]),t._v(" Documenting a package with roxygen2")]),t._v(" "),a("h3",{attrs:{id:"writing-with-roxygen2"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#writing-with-roxygen2"}},[t._v("#")]),t._v(" Writing with roxygen2")]),t._v(" "),a("p",[a("a",{attrs:{href:"https://cran.r-project.org/package=roxygen2",target:"_blank",rel:"noopener noreferrer"}},[t._v("roxygen2"),a("OutboundLink")],1),t._v(" is a package created by Hadley Wickham to facilitate documentation.")]),t._v(" "),a("p",[t._v("It allows to include the documentation inside the R script, in lines starting by "),a("code",[t._v("#'")]),t._v(". The different parameters passed to the documentation start with an "),a("code",[t._v("@")]),t._v(", for example the creator of a package will by written as follow:")]),t._v(" "),a("div",{staticClass:"language-r extra-class"},[a("pre",{pre:!0,attrs:{class:"language-r"}},[a("code",[a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("#' @author The Author")]),t._v("\n\n")])])]),a("p",[t._v("For example, if we wanted to document the following function:")]),t._v(" "),a("div",{staticClass:"language-r extra-class"},[a("pre",{pre:!0,attrs:{class:"language-r"}},[a("code",[t._v("mean"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("<-")]),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("x"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v(" sum"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("x"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("/")]),t._v("length"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("x"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n\n")])])]),a("p",[t._v("We will want to write a small description to this function, and explain the parameters with the following (each line will be explained and detailed after):")]),t._v(" "),a("div",{staticClass:"language-r extra-class"},[a("pre",{pre:!0,attrs:{class:"language-r"}},[a("code",[a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("#' Mean")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("#'")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("#' A function to compute the mean of a vector")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("#' @param x A numeric vector")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("#' @keyword mean")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("#' @importFrom base sum")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("#' @export")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("#' @examples")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("#' mean(1:3)")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("#' \\dontrun{ mean(1:1e99) }")]),t._v("\nmean"),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("<-")]),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("function")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("x"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v(" sum"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("x"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("/")]),t._v("length"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("x"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n\n")])])]),a("ul",[a("li",[t._v("The first line "),a("code",[t._v("#' Mean")]),t._v(" is the title of the documentation, the following lines make the corpus.")]),t._v(" "),a("li",[t._v("Each parameter of a function must be detailed through a relevant "),a("code",[t._v("@param")]),t._v(". "),a("code",[t._v("@export")]),t._v(" indicated that this function name should be exported, and thus can be called when the package is loaded.")]),t._v(" "),a("li",[a("code",[t._v("@keyword")]),t._v(" provides relevant keywords when looking for help")]),t._v(" "),a("li",[a("code",[t._v("@importFrom")]),t._v(" lists all functions to import from a package that will be used in this function or in you package. Note that importing the complete namespace of a package can be done with "),a("code",[t._v("@import")])]),a("li",[t._v("The examples are then written below the "),a("code",[t._v("@example")]),t._v(" tag.\n"),a("ul")]),t._v(" "),a("li",[t._v("The first one will be evaluated when the package is built;")]),t._v(" "),a("li",[t._v("The second one will not - usually to prevent long computations - due to the "),a("code",[t._v("\\dontrun")]),t._v(" command.")])]),t._v(" "),a("h3",{attrs:{id:"building-the-documentation"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#building-the-documentation"}},[t._v("#")]),t._v(" Building the documentation")]),t._v(" "),a("p",[t._v("The documentation can be created using "),a("code",[t._v("devtools::document()")]),t._v(". Note also that "),a("code",[t._v("devtools::check()")]),t._v(" will automatically create a documentation and will report missing arguments in the documentation of functions as warnings.")]),t._v(" "),a("h4",{attrs:{id:"parameters"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#parameters"}},[t._v("#")]),t._v(" Parameters")]),t._v(" "),a("table",[a("thead",[a("tr",[a("th",[t._v("Parameter")]),t._v(" "),a("th",[t._v("details")])])]),t._v(" "),a("tbody",[a("tr",[a("td",[t._v("author")]),t._v(" "),a("td",[t._v("Author of the package")])]),t._v(" "),a("tr",[a("td",[t._v("examples")]),t._v(" "),a("td",[t._v("The following lines will be examples on how to use the documented function")])]),t._v(" "),a("tr",[a("td",[t._v("export")]),t._v(" "),a("td",[t._v("To export the function - i.e. make it callable by users of the package")])]),t._v(" "),a("tr",[a("td",[t._v("import")]),t._v(" "),a("td",[t._v("Package(s) namespace(s) to import")])]),t._v(" "),a("tr",[a("td",[t._v("importFrom")]),t._v(" "),a("td",[t._v("Functions to import from the package (first name of the list)")])]),t._v(" "),a("tr",[a("td",[t._v("param")]),t._v(" "),a("td",[t._v("Parameter of the function to document")])])])])])}),[],!1,null,null,null);e.default=o.exports}}]);