-
Notifications
You must be signed in to change notification settings - Fork 35
Contributing code to ANTsR
A brief guide to writing ANTsR code.
Before doing any work, it's a good idea to search the existing issues list and then if necessary create a new issue to discuss your proposed changes.
Anyone can fork the repository, make and test their changes, then issue a pull request. We can then review the changes and merge the pull request into ANTsR. You can also merge from the upstream repository into your fork - this is important for keeping in sync with other developers.
Learn more about working with issues and pull requests on Github
To build and test the documentation, install pandoc and pandoc-citeproc. Install the latest markdown packages with:
devtools::install_github("rstudio/rmarkdown")
Some of the vignettes use additional dependencies, listed here.
- Use
<-for assignment - TODO Naming conventions
- TODO Other style points
R functions must be properly documented with roxygen. Each user-exposed function must be documented (see the existing code for examples). The documentation is written in the .R file itself, the .rmd files in the man/ directory are automatically generated and should not be edited by hand.
Example function documentation for myFunction.R:
#' Concise one-sentence description of function.
#'
#' Expanded description of function.
#'
#' @param paramName a parameter to the function.
#' @param anotherParam all parameters must be documented
#' @return what is returned by the function, or "None" if nothing.
#' @author Cook PA, OtherAuthor A
#' @examples
#' # Simple examples, must run successfully and quickly. These will be tested.
#' \dontrun{
#' Examples in here are not run, used for examples that are too long, or which
#' require user input, or can't run automatically for other reasons. These examples
#' are useful to demonstrate more "real world" use, but they are not checked.
#'
#' The developer must verify these and keep them up to date.
#' }
myFunction <- function(paramName, anotherParam = defaultValue) {
library(roxygen2)
setwd("/home/me/myAntsR")
roxygenize()
devtools::check("/path/to/ANTsR")
Self-contained tests should be included as examples in the function's man page. Tests must be fast (< 5 seconds, faster if possible), as they are all run when the code is checked using devtools or R CMD CHECK. Longer examples can be included in a \dontrun{} block. This is useful to share examples that are too long to run automatically, but might still be useful for testing offline.
The other purpose of the examples is to demonstrate the use of the function. This can be accomplished by defining realistic use cases as tests, even with very simplified data. Using clear naming in tests, and explaining the steps with comments, is also helpful.
TODO Why vignettes are useful
TODO explain what Travis does and how to interpret results.