3 Documenting Your Dataset
In the next steps, the goal is to document not only the dataset itself but also the functions and the package as a whole. The individual steps are visualized in the figure below.
3.1 Setting Up and Writing Documentation with Roxygen
To begin documenting your dataset, start by initializing Roxygen documentation. Open your R console within the project and run the following command:
setup_roxygen()This will create the necessary documentation files in the R/ folder of your project, setting up the foundation for detailed documentation.
3.1.1 Writing Documentation
Once the documentation files are generated, navigate to the R/ folder in your project. Each file in this folder, with a .R extension, represents a dataset or function. Open these files and provide a human-readable title and description using Roxygen comments (lines that start with #'). For instance, you could use the following format to document your dataset:
#' Title of Your Dataset
#'
#' A brief description of what the dataset contains and its purpose.
#'
#' @format A data frame with X rows and Y columns:
#' \describe{
#' \item{column1}{Description of column1}
#' \item{column2}{Description of column2}
#' ...
#' }
#' @source Where the data comes from (if applicable)
"dataset_name"This method allows you to provide clear, concise details about each dataset, ensuring that users understand its structure and purpose.
3.1.2 Updating Your GitHub Repository
Once you’ve completed the documentation, it’s time to update your GitHub repository. In RStudio, go to the “Git” tab. Stage all the changed files by checking the boxes next to them, then click “Commit”. Write a meaningful commit message, such as “Add Roxygen documentation for dataset”, and click “Push” to update your repository with the latest changes.
3.1.3 Finalizing and Installing the Documentation
Now that your documentation is written, run the following commands in your R console:
devtools::document()
devtools::check()
devtools::install()These commands will generate the documentation from your Roxygen comments, check for any issues in the package, and install it locally. If you receive a warning about the license, don’t worry, as it will be addressed in the next section.
3.2 Updating the DESCRIPTION File
To complete your package documentation, you’ll need to update the DESCRIPTION file with author information and other key details.
3.2.2 Documenting Other Contributors
To ensure proper credit is given, create a new issue in your GitHub repository titled “Author Information for DESCRIPTION File”. List all contributors, including their full name, email address, role (e.g., aut for authors or ctb for contributors), and ORCID (if applicable).
For each additional contributor, run a similar command:
use_author(given = "Coauthor First Name", family = "Coauthor Last Name", role = "aut")3.2.3 Updating the DESCRIPTION File
After adding all contributors, open the DESCRIPTION file in your project and ensure the title and description reflect the purpose of your package accurately. Then, in your R console, run:
update_description()This will update fields such as version, authors, and dependencies. Review the DESCRIPTION file to make sure all information is accurate.
3.2.4 Final Documentation Check
To complete the process, run the following commands again:
devtools::document()
devtools::check()
devtools::install()These steps will ensure your package is fully documented, checked for errors, and ready for use.