Docs Update for Roxygen2 R6 Support (#323)

uptake · May 3, 2024 · 43d40ba · 43d40ba
1 parent b3a95de
commit 43d40ba
Show file tree

Hide file tree

Showing 46 changed files with 1,437 additions and 1,768 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -38,5 +38,4 @@ Suggests:
 License: BSD_3_clause + file LICENSE
 URL: https://github.com/uptake/pkgnet, https://uptake.github.io/pkgnet/
 BugReports: https://github.com/uptake/pkgnet/issues
-RoxygenNote: 7.1.0
-Roxygen: list(r6 = FALSE)
+RoxygenNote: 7.3.1
diff --git a/NAMESPACE b/NAMESPACE
@@ -65,9 +65,7 @@ importFrom(utils,browseURL)
 importFrom(utils,installed.packages)
 importFrom(utils,packageDescription)
 importFrom(visNetwork,visEdges)
-importFrom(visNetwork,visGroups)
 importFrom(visNetwork,visHierarchicalLayout)
 importFrom(visNetwork,visIgraphLayout)
-importFrom(visNetwork,visLegend)
 importFrom(visNetwork,visNetwork)
 importFrom(visNetwork,visOptions)
diff --git a/NEWS.md b/NEWS.md
@@ -5,8 +5,12 @@
 
 ## CHANGES
 * Updated `pkgnet-intro` vignette to include information on the Class Inheritance Reporter and other minor edits. 
+<<<<<<< HEAD
 * Recursive functions `.parse_function` and `.parse_R6_expression` made tolerant to control statemets like `break` or `next` that would break the recursion. (#322)
 * Excessive warnings removed for custom `vignette_path` param in `CreatePackageVignette()` (#322)
+=======
+* Updated R6 class documentation to be in line with current `roxygen2` standards. 
+>>>>>>> df2fdd4 (latest R6 doc standards for roxygen and pkgdown)
 
 ## BUGFIXES
 * `CreatePackageReporter()` failing on Windows to build package coverage when `report_path` specified. (#322) 

diff --git a/R/AbstractGraphReporter.R b/R/AbstractGraphReporter.R
@@ -1,75 +1,31 @@
-#' @title Network Reporters for Packages
-#' @name NetworkReporters
-#' @keywords internal
-#' @concept Reporters
-#' @description \pkg{pkgnet} defines several package reporter R6 classes that model
-#'     a particular network aspect of a package as a graph. These network
-#'     reporter classes are extended from \code{AbstractGraphReporter}, which
-#'     itself extends the \code{\link[=PackageReporters]{AbstractPackageReporter}}
-#'     with graph-modeling-related functionality.
+#' Abstract Network Reporter Class
 #'
-#'     This article describes the additional fields added by the
-#'     \code{AbstractGraphReporter} class definition.
+#' @description
+#' \pkg{pkgnet} defines several package reporter R6 classes that model
+#' a particular network aspect of a package as a graph. These network
+#' reporter classes are extended from \code{AbstractGraphReporter}, which
+#' itself extends the \code{\link[=AbstractPackageReporter]{AbstractPackageReporter}}
+#' with graph-modeling-related functionality. 
 #'
-#' @section Public Methods:
-#' \describe{
-#'     \item{\code{calculate_default_measures()}}{
-#'         \itemize{
-#'             \item{Calculates the default node and network measures for this
-#'                reporter.
-#'             }
-#'             \item{\bold{Returns:}}{
-#'                 \itemize{
-#'                     \item{Self, invisibly.}
-#'                 }
-#'             }
-#'         }
-#'     }
-#' }
-#' @section Public Fields:
-#' \describe{
-#'     \item{\bold{\code{nodes}}}{a data.table, containing information about
-#'        the nodes of the network the reporter is analyzing. The \code{node}
-#'        column acts the identifier. Read-only.
-#'     }
-#'     \item{\bold{\code{edges}}}{a data.table, containing information about
-#'        the edge connections of the network the reporter is analyzing. Each
-#'        row is one edge, and the columns \code{SOURCE} and \code{TARGET}
-#'        specify the node identifiers. Read-only.
-#'     }
-#'     \item{\bold{\code{network_measures}}}{a list, containing any measures
-#'        of the network calculated by the reporter. Read-only.
-#'     }
-#'     \item{\bold{\code{pkg_graph}}}{a graph model object. See \link{DirectedGraph}
-#'        for additional documentation. Read-only.
-#'     }
-#'     \item{\bold{\code{graph_viz}}}{a graph visualization object. A
-#'        \code{\link[visNetwork:visNetwork]{visNetwork::visNetwork}} object.
-#'        Read-only.
-#'     }
-#'     \item{\bold{\code{layout_type}}}{a character string, the current layout
-#'        type for the graph visualization. Can be assigned a new valid layout
-#'        type value. Use use
-#'        \code{grep("^layout_\\\\S", getNamespaceExports("igraph"), value = TRUE)}
-#'        to see valid options.
-#'     }
-#' }
-NULL
-
-
+#' This article describes the additional fields added by the \code{AbstractGraphReporter} class definition.
+#' @keywords internal
+#' @concept Reporters
 #' @importFrom R6 R6Class
 #' @importFrom DT datatable formatRound
 #' @importFrom data.table data.table copy setkeyv
 #' @importFrom assertthat assert_that
 #' @importFrom grDevices colorRamp colorRampPalette rgb
 #' @importFrom magrittr %>%
 #' @importFrom visNetwork visNetwork visIgraphLayout visEdges visOptions
-#' visGroups visLegend
+# visGroups visLegend
 AbstractGraphReporter <- R6::R6Class(
     "AbstractGraphReporter"
     , inherit = AbstractPackageReporter
 
     , public = list(
+        #' @description
+        #' Calculates the default node and network measures for this reporter.
+        #' @return Self, invisibly.
         calculate_default_measures = function() {
             self$pkg_graph$node_measures(
                 measures = self$pkg_graph$default_node_measures
@@ -80,6 +36,9 @@ AbstractGraphReporter <- R6::R6Class(
             return(invisible(self))
         }
 
+        #' @description 
+        #' Creates a summary table formatted for display.
+        #' @return A \code{DT} object
         , get_summary_view = function(){
 
             # Create DT for display of the nodes data.table
@@ -108,26 +67,36 @@ AbstractGraphReporter <- R6::R6Class(
     ) # /public
 
     , active = list(
-
+        #' @field nodes A data.table, containing information about
+        #' the nodes of the network the reporter is analyzing. The \code{node} 
+        #' column acts the identifier. Read-only.
         nodes = function(){
             if (is.null(private$cache$nodes)){
                 private$extract_nodes()
             }
             return(private$cache$nodes)
         },
 
+        #' @field edges A data.table, containing information about
+        #' the edge connections of the network the reporter is analyzing. Each
+        #' row is one edge, and the columns \code{SOURCE} and \code{TARGET}
+        #' specify the node identifiers. Read-only.
         edges = function(){
             if (is.null(private$cache$edges)) {
                 private$extract_edges()
             }
             return(private$cache$edges)
         },
 
+        #' @field network_measures A list, containing any measures 
+        #' of the network calculated by the reporter. Read-only.
         network_measures = function() {
             return(c(private$cache$network_measures
                      , private$cache$pkg_graph$graph_measures()))
         },
 
+        #' @field pkg_graph a graph model object. See \link{DirectedGraph}
+        #' for additional documentation. Read-only.
         pkg_graph = function(){
             if (is.null(private$cache$pkg_graph)){
                 if (is.null(private$graph_class)) {
@@ -150,13 +119,18 @@ AbstractGraphReporter <- R6::R6Class(
             return(private$cache$pkg_graph)
         },
 
+        #' @field graph_viz a graph visualization object. A 
+        #' \code{\link[visNetwork:visNetwork]{visNetwork::visNetwork}} object.
+        #' Read-only.
         graph_viz = function(){
             if (is.null(private$cache$graph_viz)) {
                 private$cache$graph_viz <- private$plot_network()
             }
             return(private$cache$graph_viz)
         },
 
+        #' @field layout_type a character string, the current layout type for the graph visualization. 
+        #' Can be assigned a new valid layout type value. Use use \code{grep("^layout_\\\\S", getNamespaceExports("igraph"), value = TRUE)} to see valid options.
         layout_type = function(layout) {
             # If user using <- assignment, set layout and reset viz
             if (!missing(layout)) {

diff --git a/R/AbstractPackageReporter.R b/R/AbstractPackageReporter.R
@@ -1,108 +1,13 @@
-#' @title Package Reporters
-#' @name PackageReporters
+#' Abstract Package Reporter
+#' 
+#' @description 
+#' pkgnet defines several package reporter R6 classes that analyze 
+#' some particular aspect of a package. These reporters share common
+#' functionality and interfaces defined by a base reporter class
+#' \code{AbstractPackageReporter}.
+#'
 #' @keywords internal
 #' @concept Reporters
-#' @description pkgnet defines several package reporter R6 classes that analyze
-#'     some particular aspect of a package. These reporters share common
-#'     functionality and interfaces defined by a base reporter class
-#'     \code{AbstractPackageReporter}.
-#' @section Class Constructor:
-#' \describe{
-#'     \item{\code{}}{
-#'         \itemize{
-#'             \item{Initialize an instance of the reporter.}
-#'             \item{\bold{Returns:}}{
-#'                 \itemize{
-#'                     \item{Instantiated reporter object. Note that this
-#'                        reporter object isn't useful yet until you use the
-#'                        \code{set_package} method to set a package.
-#'                     }
-#'                 }
-#'             }
-#'         }
-#'     }
-#' }
-#'
-#' @section Public Methods:
-#' \describe{
-#'     \item{\code{set_package(pkg_name, pkg_path = NULL)}}{
-#'         \itemize{
-#'             \item{Set the package that the reporter will analyze. This can
-#'                 only be done once for a given instance of a reporter.
-#'                 Instantiate a new copy of the reporter if you need to analyze
-#'                 a different package.
-#'             }
-#'             \item{\bold{Args:}}{
-#'                 \itemize{
-#'                     \item{\bold{\code{pkg_name}}: character string, name of
-#'                      package
-#'                  }
-#'                     \item{\bold{\code{pkg_path}}: character string, optional
-#'                     directory path to source code of the package. It is used
-#'                     for calculating test coverage. It can be an absolute or
-#'                     relative path.
-#'                  }
-#'                 }
-#'             }
-#'             \item{\bold{Returns:}}{
-#'                 \itemize{
-#'                     \item{Self, invisibly.}
-#'                 }
-#'             }
-#'         }
-#'     }
-#'     \item{\code{get_summary_view()}}{
-#'         \itemize{
-#'             \item{Returns an htmlwidget object that summarizes the analysis
-#'                 of the reporter. Used when creating a
-#'                 \link[=CreatePackageReport]{package report}.
-#'             }
-#'             \item{\bold{Returns:}}{
-#'                 \itemize{
-#'                     \item{\link[htmlwidgets:htmlwidgets-package]{htmlwidget}
-#'                         object
-#'                     }
-#'                 }
-#'             }
-#'         }
-#'     }
-#' }
-#'
-#' @section Public Fields:
-#' \describe{
-#'     \item{\bold{\code{pkg_name}}}{character string, name of set package.
-#'         Read-only.
-#'     }
-#'     \item{\bold{\code{report_markdown_path}}}{character string, path to
-#'         R Markdown template for this reporter. Read-only.
-#'     }
-#' }
-#'
-#' @section Special Methods:
-#' \describe{
-#'     \item{\code{clone(deep = FALSE)}}{
-#'         \itemize{
-#'             \item{Method for copying an object. See
-#'                 \href{https://adv-r.hadley.nz/r6.html#r6-semantics}{\emph{Advanced R}}
-#'                 for the intricacies of R6 reference semantics.
-#'             }
-#'             \item{\bold{Args:}}{
-#'                 \itemize{
-#'                     \item{\bold{\code{deep}}: logical. Whether to recursively
-#'                     clone nested R6 objects.
-#'                  }
-#'                 }
-#'             }
-#'             \item{\bold{Returns:}}{
-#'                 \itemize{
-#'                     \item{Cloned object of this class.}
-#'                 }
-#'             }
-#'         }
-#'     }
-#' }
-NULL
-
 #' @importFrom R6 R6Class
 #' @importFrom assertthat assert_that is.string
 #' @importFrom tools file_path_as_absolute
@@ -111,6 +16,14 @@ AbstractPackageReporter <- R6::R6Class(
 
     public = list(
 
+        #' @description
+        #' Set the package that the reporter will analyze. This can 
+        #' only be done once for a given instance of a reporter. 
+        #' Instantiate a new copy of the reporter if you need to analyze a different package.
+        #' @param pkg_name (character string) name of package
+        #' @param pkg_path (character string) optional directory path to source code of the package. 
+        #' It is used for calculating test coverage. It can be an absolute or relative path.
+        #' @return Self, invisibly.
         set_package = function(pkg_name, pkg_path = NULL) {
 
             # Packages can only be set once
@@ -141,17 +54,22 @@ AbstractPackageReporter <- R6::R6Class(
             return(invisible(self))
         },
 
+        #' @description Returns an htmlwidget object that summarizes the analysis of the reporter. 
+        #' Used when creating a \link[=CreatePackageReport]{package report}.
+        #' @return Self, invisibly.
         get_summary_view  = function(){
             stop("get_summary_view has not been implemented.")
         }
     ),
 
     active = list(
 
+        #' @field pkg_name (character string) name of set package. Read-only.
         pkg_name = function(){
             return(private$private_pkg_name)
         },
 
+        #' @field report_markdown_path (character string) path to R Markdown template for this reporter. Read-only.
         report_markdown_path = function(){
             log_fatal("this reporter does not have a report markdown path")
         }