resolving merge conflict, rebuilding roxygen docs

.gitignore

@@ -1,7 +1,10 @@
+.DS_Store
+
 inst/doc
+docs
+
 .Rproj.user
 .Rhistory
 .RData
 .Ruserdata
 .html
-docs

DESCRIPTION

@@ -36,8 +36,9 @@ Imports:
  covr,
  rvest,
  memoise,
- janitor
-RoxygenNote: 6.1.1
+ janitor,
+ cranlogs
+RoxygenNote: 7.0.2
 Suggests:
  knitr,
  rmarkdown,

NAMESPACE

@@ -6,11 +6,13 @@ S3method("[",pkg_ref)
 S3method("[<-",pkg_ref)
 S3method("[[",pkg_ref)
 S3method("[[<-",pkg_ref)
+S3method(.DollarNames,pkg_ref)
 S3method(as_pkg_ref,character)
 S3method(as_pkg_ref,default)
 S3method(as_pkg_ref,pkg_ref)
 S3method(as_tibble,list_of_pkg_ref)
 S3method(as_tibble,pkg_ref)
+S3method(assess_downloads_1yr,pkg_ref)
 S3method(assess_export_help,pkg_install)
 S3method(assess_has_news,pkg_ref)
 S3method(assess_license,pkg_ref)
@@ -21,12 +23,14 @@ S3method(format,pkg_metric)
 S3method(format,pkg_metric_error)
 S3method(format,pkg_missing)
 S3method(format,pkg_ref)
+S3method(names,pkg_ref)
 S3method(pillar_shaft,list_of_pkg_metric)
 S3method(pillar_shaft,list_of_pkg_ref)
 S3method(pillar_shaft,pkg_metric_error)
 S3method(print,dev_hint)
 S3method(print,pkg_ref)
 S3method(score,default)
+S3method(score,pkg_metric_downloads_1yr)
 S3method(score,pkg_metric_error)
 S3method(score,pkg_metric_export_help)
 S3method(score,pkg_metric_has_news)
@@ -42,6 +46,7 @@ export(.risk_weights)
 export(all_assessments)
 export(as_pkg_ref)
 export(assess)
+export(assess_downloads_1yr)
 export(assess_export_help)
 export(assess_has_news)
 export(assess_last_30_bugs_status)
@@ -60,6 +65,7 @@ export(score_error_NA)
 export(score_error_default)
 export(score_error_zero)
 export(summarize_risk)
+import(cranlogs)
 import(dplyr)
 import(janitor)
 import(memoise)

R/assess.R

@@ -1,11 +1,81 @@
+#' Helper for creating a roxygen header from template for assess_* functions
+#'
+#' @param name the name of the assessment, assuming naming conventions are
+#' followed
+#' @param return_type an optional added commentary about the return type of the
+#' assessment function
+#'
+#' @return roxygen section template for assess family functions
+#'
+#' @examples
+#' \dontrun{
+#' #' @eval roxygen_assess_family(
+#' "has_news",
+#' "an integer value indicating the number of discovered NEWS files")
+#' }
+#'
+roxygen_assess_family <- function(name,
+ return_type = "an atomic assessment result") {
+
+ assess_func <- sprintf("assess_%s", name)
+ score_func <- sprintf("score.pkg_metric_%s", name)
+
+ if (!assess_func %in% getNamespaceExports(utils::packageName()) ||
+ !score_func %in% getNamespaceExports(utils::packageName())) {
+ stop(sprintf(paste0(
+ "All assess_* functions must have a corresponding score.* method ",
+ "implemented.\n\n",
+ "To remove build errors, ensure that the following functions are ",
+ "implemented:\n\n",
+ " %s()\n",
+ " %s()\n")),
+ assess_func,
+ score_func)
+ }
+
+ c("@param x a \\code{pkg_ref} package reference object",
+ "@param ... additional arguments passed on to S3 methods, rarely used",
+ sprintf("@return a \\code{pkg_metric} containing %s", return_type),
+ "@family \\code{assess_*} functions",
+ sprintf("@seealso \\code{\\link{%s}}", score_func),
+ sprintf("@examples assess_%s(pkg_ref(\"%s\"))", name, packageName()))
+}
+
+
+
+#' Helper for creating a roxygen itemized list for assess_* functions
+#'
+#' @return roxygen section template for assess family function catalog
+#'
+#' @examples
+#' \dontrun{
+#' #' @eval assess_family_catalog_roxygen()
+#' }
+#'
+roxygen_assess_family_catalog <- function() {
+ assessments <- all_assessments()
+ info <- lapply(assessments, attr, "label")
+ missing_label <- vapply(info, is.null, logical(1L))
+ info[missing_label] <- names(info)[missing_label]
+
+ c("@section Assessment function catalog:",
+ "\\describe{",
+ sprintf('\\item{\\code{\\link{%s}}}{%s}', names(info), info),
+ "}")
+}
+
+
+
 #' A default list of assessments to perform for each package
 #'
 #' @return a list of assess_* functions exported from riskmetric
 #'
 #' @importFrom utils packageName
 #' @export
 all_assessments <- function() {
- fs <- grep("^assess_", getNamespaceExports(utils::packageName()), value = TRUE)
+ fs <- grep("^assess_[^.]*$",
+ getNamespaceExports(utils::packageName()),
+ value = TRUE)
  Map(getExportedValue, fs, ns = list(utils::packageName()))
 }
 
@@ -40,10 +110,14 @@ use_assessments_column_names <- function(x) {
 
 
 
-#' Function for applying assess_* family of functions to packages
+#' Apply assess_* family of functions to a package reference
+#'
+#' By default, use all \code{assess_*} funtions in the \code{riskmetric}
+#' namespace and produce a \code{\link[tibble]{tibble}} with one column per
+#' assessment applied.
 #'
-#' @param x A single package reference object or \code{\link[tibble]{tibble}} of
-#' package references to assess
+#' @param x A single \code{\link{pkg_ref}} object or
+#' \code{\link[tibble]{tibble}} of package references to assess
 #' @param assessments A list of assessment functions to apply to each package
 #' reference. By default, a list of all exported assess_* functions from the
 #' riskmetric package.
@@ -57,7 +131,9 @@ use_assessments_column_names <- function(x) {
 #' metric objects returned when the assessment was called with the associated
 #' pacakge reference.
 #'
-#' @seealso as_tibble.pkg_ref
+#' @eval roxygen_assess_family_catalog()
+#'
+#' @family \code{assess_*} functions
 #'
 #' @importFrom tibble as_tibble
 #' @importFrom vctrs new_list_of
@@ -89,47 +165,3 @@ assess <- function(x, assessments = all_assessments(), ...,
 
  x
 }
-
-
-
-#' Helper for creating a roxygen header from template for assess_* functions
-#'
-#' @param name the name of the assessment, assuming naming conventions are
-#' followed
-#' @param return_type an optional added commentary about the return type of the
-#' assessment function
-#'
-#' @return roxygen section template for assess family functions
-#'
-#' @examples
-#' \dontrun{
-#' #' @eval assess_family_roxygen(
-#' "has_news",
-#' "an integer value indicating the number of discovered NEWS files")
-#' }
-#'
-assess_family_roxygen <- function(name,
- return_type = "an atomic assessment result") {
-
- assess_func <- sprintf("assess_%s", name)
- score_func <- sprintf("score.pkg_metric_%s", name)
-
- if (!assess_func %in% getNamespaceExports(utils::packageName()))
- warning(sprintf(paste0("Error when generating documentation for %s. ",
- "Associated assessment function `%s` was not found in the `riskmetric` ",
- "package. Please provide one to complete documentation."),
- name, assess_func))
-
- if (!score_func %in% getNamespaceExports(utils::packageName()))
- warning(sprintf(paste0("Error when generating documentation for %s. ",
- "Associated scoring function `%s` was not found in the `riskmetric` ",
- "package. Please provide one to complete documentation."),
- name, score_func))
-
- c("@param x a \\code{pkg_ref} package reference object",
- "@param ... additional arguments passed on to S3 methods, rarely used",
- sprintf("@return a \\code{pkg_metric} containing %s", return_type),
- "@family \\code{assess_*} functions",
- sprintf("@seealso \\code{\\link{%s}}", score_func),
- sprintf("@examples assess_%s(pkg_ref(\"%s\"))", name, packageName()))
-}

R/assess_downloads.r

@@ -0,0 +1,49 @@
+#' Assess a package for the number of downloads in the past year
+#'
+#' @details The more times a package has been downloaded the more extensive the user testing and the greater chance there is of someone finding a bug and logging it.
+#'
+#' @eval assess_family_roxygen(
+#' "downloads_1yr",
+#' "a numeric value between [0,1] indicating the volume of downloads")
+#'
+#' @export
+assess_downloads_1yr <- function(x, ...){
+ UseMethod("assess_downloads_1yr")
+}
+
+# assign a friendly name for assess column
+attr(assess_downloads_1yr,"column_name") <- "downloads_1yr"
+attr(assess_downloads_1yr,"label") <- "number of downloads in the past year"
+
+
+
+#' @export
+assess_downloads_1yr.pkg_ref <- function(x, ...) {
+ downloads_1yr <- sum(x$downloads$count)
+ pkg_metric(downloads_1yr, class = "pkg_metric_downloads_1yr")
+}
+
+
+
+#' Defining an Assessment Scoring Function
+#' Score a package for the number of downloads in the past year
+#'
+#' Convert the number of downloads \code{x} in the past year into a validation
+#' score [0,1] \deqn{ 1 - 150,000 / (x + 150,000) }
+#'
+#' The scoring function is a simplification of the classic logistic curve \deqn{
+#' 1 / (1 + exp(-k(x-x[0])) } with a log scale for the number of downloads
+#' \eqn{x = log(x)}, sigmoid midpoint is 1000 downloads, ie. \eqn{x[0] =
+#' log(1,000)}, and logistic growth rate of \eqn{k = 0.5}.
+#'
+#' \deqn{ 1 - 1 / (1 + exp(log(x)-log(1.5e5))) = 1 - 150,000 / (x + 150,000) }
+#'
+#' @eval score_family_roxygen("downloads_1yr")
+#' @return numeric value between \code{0} (low) and \code{1} (high download
+#' volume) converting the number of downloads.
+#'
+#' @export
+score.pkg_metric_downloads_1yr <- function(x, ...) {
+ # simplification from logistic: 1 - 1 / (1 + exp(log(x)-log(1.5e5)))
+ 1 - 1.5e5 / (x + 1.5e5)
+}

R/assess_export_help.R

@@ -1,6 +1,6 @@
 #' Assess a package for availability of documentation for exported values
 #'
-#' @eval assess_family_roxygen(
+#' @eval roxygen_assess_family(
 #' "export_help",
 #' "a logical vector indicating existence of documentation for each namespace export")
 #'

R/assess_has_news.R

@@ -1,6 +1,6 @@
 #' Assess a package for the presence of a NEWS file
 #'
-#' @eval assess_family_roxygen(
+#' @eval roxygen_assess_family(
 #' "has_news",
 #' "an integer value indicating the number of discovered NEWS files")
 #'

R/assess_license.R

@@ -1,6 +1,6 @@
 #' Assess a package for an up-to-date NEWS file
 #'
-#' @eval assess_family_roxygen(
+#' @eval roxygen_assess_family(
 #' "license",
 #' "a string indicating the license under which the package is released")
 #'

R/assess_news_current.R

@@ -1,6 +1,6 @@
 #' Assess a package for an up-to-date NEWS file
 #'
-#' @eval assess_family_roxygen(
+#' @eval roxygen_assess_family(
 #' "news_current",
 #' "a logical vector indicating whether each discovered NEWS file is up-to-date")
 #'