Fix cran feedback (#103)

[skip vbump] [skip lintr] [skip lint]

DESCRIPTION

@@ -1,20 +1,23 @@
 Package: rlistings
 Title: Clinical Trial Style Data Readout Listings
-Version: 0.2.0
+Version: 0.2.1
 Date: 2023-03-01
 Authors@R: c(
     person("Gabriel", "Becker", , "gabembecker@gmail.com", role = c("aut", "cre")),
     person("Adrian", "Waddell", , "adrian.waddell@gene.com", role = "aut"),
     person("Joe", "Zhu", , "joe.zhu@roche.com", role = "aut"),
+    person("Davide", "Garolini", , "davide.garolini@roche.com", role = "ctb"),
+    person("Emily", "de la Rua", , "emily.de_la_rua@contractors.roche.com", role = "ctb"),
+    person("Abinaya", "Yogasekaram", , "abinaya.yogasekaram@contractors.roche.com", role = "ctb"),
     person("F. Hoffmann-La Roche AG", role = c("cph", "fnd"))
   )
 Description: Listings are often part of the submission of clinical trial
     data in regulatory settings.  We provide a framework for the specific
     formatting features often used when displaying large datasets in that
     context.
-License: Apache License 2.0 | file LICENSE
-URL: http://github.com/insightsengineering/rlistings
-BugReports: http://github.com/insightsengineering/rlistings/issues
+License: Apache License 2.0
+URL: https://github.com/insightsengineering/rlistings
+BugReports: https://github.com/insightsengineering/rlistings/issues
 Depends: 
     formatters (>= 0.4.0),
     methods,

NEWS.md

@@ -1,4 +1,4 @@
-## rlistings 0.2.0
+## rlistings 0.2.1
 
 ### Enhancements
  * Extend page-size machinery in pagination by allowing the page specification (`page_type`, `pg_width`,

R/paginate_listing.R

@@ -23,23 +23,24 @@
 #' @rdname paginate
 #'
 #' @examples
-#' # Create a standard listing
 #' dat <- ex_adae
 #' lsting <- as_listing(dat[1:25, ], disp_cols = c("USUBJID", "AESOC", "RACE", "AETOXGR", "BMRKR1"))
 #'
 #' mat <- matrix_form(lsting)
 #'
 #' cat(toString(mat))
 #'
-#' # Vertical pagination
 #' paginate_listing(lsting, lpp = 10)
 #'
-#' # Horizontal pagination
 #' paginate_listing(lsting, cpp = 100, lpp = 40)
 #'
-#' # Use `verbose = TRUE` to display more descriptive warnings or errors
-#' # paginate_listing(lsting, cpp = 80, lpp = 40, verbose = TRUE)
+#' paginate_listing(lsting, cpp = 80, lpp = 40, verbose = TRUE)
 #' @export
+#'
+#' @return for `paginate_listing` a list containing separate
+#' `listing_df` objects for each page, for `pag_listing_indices`,
+#' a list of indices in the direction being paginated corresponding
+#' to the individual pages in that dimension.
 paginate_listing <- function(lsting,
                              page_type = "letter",
                              font_family = "Courier",

R/rlistings.R

@@ -175,11 +175,17 @@ get_keycols <- function(df) {
 }
 
 #' @export
-#' @inheritParams formatters::matrix_form
-#' @seealso [formatters::matrix_form()] This is partially inherited from `formatters`' function
+#' @inherit formatters::matrix_form
+#' @seealso [formatters::matrix_form()] 
 #' @param indent_rownames logical(1). Silently ignored, as listings do not have row names
 #' nor indenting structure.
-#' @rdname listings
+#'
+#' @examples
+#'
+#' lsting <- as_listing(mtcars)
+#' mf <- matrix_form(lsting)
+#'
+#' @return a `MatrixPrintForm` object
 setMethod(
   "matrix_form", "listing_df",
   rix_form <- function(obj, indent_rownames = FALSE) {

R/rlistings_methods.R

@@ -38,7 +38,7 @@ basic_run_lens <- function(x) {
 }
 
 
-#' @rdname listing_methods
+#' @rdname vec_nlines
 #' @param df listing_df. The listing.
 #' @param colnm Column name
 #' @param colvec Column values based on colnm
@@ -55,12 +55,21 @@ format_colvector <- function(df, colnm, colvec = df[[colnm]]) {
   strvec
 }
 
-#' @rdname listing_methods
-#' @param vec A vector.
+#' Utilities for formatting a listing column
+#'
+#' For `vec_nlines`, calculate the number of lines each element of a column vector will
+#' take to render. For `format_colvector`,
+#'
+#' @param vec any vector. A column vector to be rendered into ASCII.
+#' @param max_width numeric (or NULL). The width the column will be
+#' rendered in.
+#' @return a numeric vector of the number of lines elementwise that
+#' will be needed to render the elements of \code{vec} to width
+#' \code{max_width}.
 #' @keywords internal
 setGeneric("vec_nlines", function(vec, max_width = NULL) standardGeneric("vec_nlines"))
 
-#' @rdname listing_methods
+#' @rdname vec_nlines
 #' @param vec A vector.
 #' @keywords internal
 setMethod("vec_nlines", "ANY", function(vec, max_width = NULL) {
@@ -81,9 +90,19 @@ setMethod("vec_nlines", "ANY", function(vec, max_width = NULL) {
 ##   ret[is.na(ret)] <- format_value(NA_character
 ## })
 
+#' Make pagination dataframe for a listing
 #' @export
 #' @inheritParams formatters::make_row_df
-#' @rdname listing_methods
+#' @param tt listing_df. The listing to be rendered
+#' @param visible_only logical(1). Ignored, as listings
+#' do not have non-visible structural elements.
+#'
+#' @examples
+#' lsting <- as_listing(mtcars)
+#' mf <- matrix_form(lsting)
+#'
+#' @return a data.frame with pagination information.
+#' @seealso \code{\link[formatters]{make_row_df}}
 setMethod(
   "make_row_df", "listing_df",
   function(tt, colwidths = NULL, visible_only = TRUE,
@@ -194,6 +213,7 @@ setMethod(
 #' @param j ANY. Passed to base `[` methods.
 #' @aliases [,listing_df-method
 #' @rdname listing_methods
+#' @keywords internal
 setMethod(
   "[", "listing_df",
   function(x, i, j, drop = FALSE) {
@@ -217,6 +237,12 @@ setMethod(
 #'     header/body separator line.
 #' @param col_gap numeric(1). Space (in characters) between columns
 #' @exportMethod toString
+#'
+#' @examples
+#' lsting <- as_listing(mtcars)
+#' toString(lsting)
+#' @return A character value containing the listing rendered into
+#' ASCII text.
 setMethod("toString", "listing_df", function(x,
                                              widths = NULL,
                                              col_gap = 3,
@@ -254,6 +280,16 @@ setMethod("toString", "listing_df", function(x,
 #' @rdname listing_methods
 #' @param obj The object.
 #' @export
+#' @return for getter methods, the value of the aspect of
+#' \code{obj}; for setter methods, \code{obj} with
+#' the relevant element of the listing updated.
+#'
+#' @examples
+#'
+#' lsting <- as_listing(mtcars)
+#' main_title(lsting) <- "Hi there"
+#'
+#' main_title(lsting)
 setMethod(
   "main_title", "listing_df",
   function(obj) attr(obj, "main_title") %||% character()