You should document all exported functions and datasets. Roxygen comment lines always start with #', the usual # for a comment, followed immediately by a single quote ': Your documentation workflow truly begins when you start to add roxygen comments above your functions. Rd files, but officially R only cares about the files themselves, not how they came to be. We think the roxygen approach is the best way to generate your. It has no effect on, e.g., how a package gets checked or built. That’s because the use of roxygen2 is purely a matter of your development workflow. Unlike with testthat, there’s no obvious opening move to declare that you’re going to use roxygen2 for documentation. We also highlight the biggest wins of using markdown with roxygen2. To get started, we’ll work through the basic roxygen2 workflow and discuss the overall structure of roxygen2 comments, which are organised into blocks and tags. You can learn more about those important topics in vignette("rd-other", package = "roxygen2"). In this chapter we’ll focus on documenting functions, but the same ideas apply to documenting datasets ( Section 7.1.2), classes and generics, and packages. Roxygen2 provides a number of tools for sharing content across documentation topics and even between topics and vignettes. In addition to formatting, the automatic hyperlinking functionality makes it much, much easier to create richly linked documentation. You can use markdown, rather than having to learn a one-off markup language that only applies to. When you modify your code, it’s easy to remember to also update your documentation. There are a few advantages to using roxygen2 :Ĭode and documentation are co-located. Then we use the roxygen2 package to generate the. Instead, we include specially formatted “roxygen comments” above the source code for each function 1. In the devtools ecosystem, we don’t edit. Rd file (“R documentation”) in the man/ directory.Rd files use a custom syntax, loosely based on LaTeX, and can be rendered to HTML, plain text, or pdf, as needed, for viewing in different contexts. Base R provides a standard way of documenting a package where each function is documented in a topic, an. In this chapter, you’ll learn about function documentation, which users access with ?somefunction or help("somefunction").
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |