gam2table(): should it be exported?

[HenrikBengtsson]

R CMD check reports on:

  Undocumented arguments in documentation object 'gam2table'
    ‘mods’ ‘modnames’
  Documented arguments not in \usage in documentation object 'gam2table':
    ‘x’ ‘xnames’ ‘include_anova_pvals’

While looking at this, I noticed that rtemis:::gam2table() is documented by not exported;

rtemis/R/glm2table.R

Lines 1 to 20 in 31cd8eb

	# glm2table.R
	# ::rtemis::
	# 2021 E.D. Gennatas www.lambdamd.org
	#' Collect summary table from list of massGLMs with same predictors, different outcome
	#' ("massy")
	#'
	#' @param x list of [glm] models
	#' @param xnames Character, vector: names of models
	#' @param include_anova_pvals Integer: 1 or 3; to output ANOVA I or III p-vals. NA to not
	#' @param warn Logical: If TRUE, warn when values < than machine eps are replaced by
	#' machine eps
	#'
	#' @return `data.table` with glm summaries
	#' @author E.D. Gennatas
	glm2table <- function(x,
	xnames = NULL,
	include_anova_pvals = NA,
	warn = TRUE) {

Should it be exported?

FWIW, it looks like R CMD check picks up another gam2table from one of the dependencies.

[egenn]

Not at this point. I added #' @keywords internal to both glm2table() and gam2table()

[HenrikBengtsson]

Got it. So, in recent versions of R (I think >= 4.3.0), R CMD check now checks all man/ pages, which I think required ditto functions to be exported. I created PR #56 that adds #' @noRd to this function to fix the check warning that you otherwise gets.

[egenn]

Should I add #' @noRd to all #' @keywords internal functions?

[egenn]

I guess that's rOpenSci's recommendation (https://devguide.ropensci.org/building.html)

[egenn]

Before reading roxygen's docs, I thought #' @keywords internal would stop docs from being rendered, instead of just excluding from documentation index.

[HenrikBengtsson]

Should I add #' @noRd to all #' @keywords internal functions?

I'm pretty sure it's only needed for non-exported functions. Note that #' @keywords internal has nothing to do with a function being exported or not; it just declares that the function/object should not be listed in the HTML help index.