From 0a43ebbeaf0f4ee8486fe30aca93baf0fa16514b Mon Sep 17 00:00:00 2001
From: Nick-Eagles <nick.eagles@libd.org>
Date: Tue, 10 Oct 2023 11:21:04 -0400
Subject: [PATCH] Add a function header with an example and documentation

---
 R/partition_info.R | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/R/partition_info.R b/R/partition_info.R
index 23acfef..ce705aa 100644
--- a/R/partition_info.R
+++ b/R/partition_info.R
@@ -1,5 +1,36 @@
-library(dplyr)
-
+#' Return a tibble containing information about partitions.
+#'
+#' This function imports the output of 'sinfo' into tibble, focusing on
+#' available vs. total CPUs and memory by either node or partition (depending
+#' on `all_nodes`).
+#'
+#' @param partition A `character(1)` vector specifying the partition to show
+#' information about. Set NULL to return info about all partitions.
+#' @param all_nodes A `logical(1)` vector. When TRUE, return one row per node.
+#' When FALSE, summarize information over nodes and return one row per
+#' partition.
+#'
+#' @return A tibble with memory and CPU information about partitions.
+#' @export
+#' @author Nicholas J. Eagles
+#' @import dplyr utils
+#'
+#' @examples
+#'
+#' #    Must be run in a SLURM environment where a 'shared' partition exists
+#' if (system("which sbatch") == 0) {
+#'     part_df <- partition_info(partition = "shared", all_nodes = FALSE)
+#'
+#'     #    Print summary of CPU availability for the 'shared' partition
+#'     print(
+#'         sprintf(
+#'             'The %s partition has %i CPUs free (%.1f%% of total)',
+#'             part_df$partition,
+#'             part_df$free_cpus,
+#'             100 * part_df$prop_free_cpus
+#'         )
+#'     )
+#' }
 partition_info <- function(partition = "shared", all_nodes = FALSE) {
     command = paste(
         #   Grab info about CPUs and memory with 'sinfo'