There are several popular ways to get your function(s) in shape for sharing with the bio3d community:

1. If you have only one function to contribute

If you have only one function to contribute then consider saving the function code into a separate file called 'FunctionName.R' (obviously replacing the FunctionName part of the file name with the name of your actual function).

Then run the 'prompt()' function to create a skeleton help file (which by default will have the name 'FunctionName.Rd'). You will then need to edit the help file following the guidelines given further below.

#!r
## Define a new function
precent.helix <- function(pdb, sse=pdb) {
   n.total <- sum(pdb$calpha)
   n.helix <- length( unbound(pdb$helix$start, pdb$helix$end) )
   return((n.helix/n.total) * 100)
}

## Save code to a separate file with a .R file extension
sink("precent.helix.R")
cat("precent.helix <- ")
precent.helix
sink()

## Generate a template help file for the function 
prompt(precent.helix)

## See where these files got saved 
getwd()

## Edit to complete the help file
## Move the .R file to the packages R folder and help file to the man folder

It is okay to update an existing .R file and then update the existing help file, but do be sure to update the usage and arguments sections, if needed

2. If you have multiple functions to contribute

Consider loading all the functions and data sets that you would like to contribute into a clean R session, and then running the 'package.skeleton()' function.

The objects in your current R session will be sorted into data and functions, skeleton help files are created for them using 'prompt()' and a DESCRIPTION file is created. The function then prints out a list of things for you to do next. Which minimally includes editing the help files following the guidelines below.

3. If you would like to use Roxygen to automate partial Rd file creation

This option is usually faster for experienced developers but can be error prone and thus not recommended for your first submission. Basically, this process will allow you to go from the R comments in the source files to Rd files. The process starts with special comments starting with #' that indicate a comment is a roxygen comment. For full details see < http://adv-r.had.co.nz/Documenting-functions.html#roxygen-process >

Documentation file guidlines

The sources of R help files are in R documentation format and have extension .Rd. The format is similar to LATEX, but only a small subset of LATEX commands are available. The documentation files can be converted into HTML, plain text, GNU info format, and LATEX.

To view an example help page see aa123.

First the name of the help page, then aliases for all topics the page documents. The title should again be only one line because it is used for the window title in HTML browsers. The descriptions should be only 1–2 paragraphs, if more text is needed it should go into the optional details section not shown in the example. Regular R users will immediately recognize most sections of Rd files from reading other help pages. The usage section should be plain R code. For regular functions it is the full header with all arguments and their default values: Copy & paste from the code and remove <- function. For data sets it is typically simply data(name).

The examples section should contain executable R code, and automatically running the code is part of checking a package. There are two special markup commands for the examples: dontrun: Everything inside \dontrun{} is not executed by the tests or example(). This is useful, e.g., for interactive functions, functions accessing the Internet etc.. Do not misuse it to make life easier for you by giving examples which cannot be executed.

There are other possible sections, and ways of specifying equations, URLs, links to other R doc- umentation, and more. The manual “Writing R Extensions” has the full list of all Rd commands.

Note that the packaging system checks that all objects are documented, that the usage corresponds to the actual definition of the function, and that the examples will run. This enforces a minimal level of accuracy on the documentation.

A note on function names

Function names should start with a letter and can contain numbers and dots. We recommend avoiding other characters (e.g. hash etc.).

Avoid using both upper and lower case letters: they make the function name hard to type and hard to remember. For example, I can never remember if it's Rgtk2 or RGTK2 or RGtk2.

4. Uploading your work to the development version of bio3d

Now you are ready to add your changes to the development version of bio3d and share these changes with other developers and users. To do this you can either email the developers or add an New Issue on the Issues tab here on bitbucket.

However, if you think you might be a regular contributor you should start using git to manage your changes and sink with those of other developers. You might also want to check out the "for developers" section of the wiki. Yeah welcome to the team!