Roxygen documentation rewrite

NAMESPACE

@@ -1,7 +1,5 @@
 # Generated by roxygen2: do not edit by hand
 
-export(AbstractGraphReporter)
-export(AbstractPackageReporter)
 export(CreatePackageReport)
 export(DefaultReporters)
 export(DependencyReporter)
@@ -14,25 +12,25 @@ importFrom(DT,formatRound)
 importFrom(R6,R6Class)
 importFrom(R6,is.R6Class)
 importFrom(assertthat,assert_that)
+importFrom(assertthat,is.flag)
 importFrom(assertthat,is.readable)
 importFrom(assertthat,is.string)
 importFrom(assertthat,is.writeable)
 importFrom(covr,package_coverage)
 importFrom(data.table,as.data.table)
 importFrom(data.table,copy)
 importFrom(data.table,data.table)
-importFrom(data.table,melt)
 importFrom(data.table,rbindlist)
-importFrom(data.table,setcolorder)
 importFrom(data.table,setkeyv)
-importFrom(data.table,setnames)
-importFrom(data.table,uniqueN)
 importFrom(futile.logger,INFO)
 importFrom(futile.logger,flog.fatal)
 importFrom(futile.logger,flog.info)
 importFrom(futile.logger,flog.threshold)
 importFrom(futile.logger,flog.warn)
 importFrom(futile.logger,logger.options)
+importFrom(grDevices,colorRamp)
+importFrom(grDevices,colorRampPalette)
+importFrom(grDevices,rgb)
 importFrom(igraph,V)
 importFrom(igraph,authority_score)
 importFrom(igraph,betweenness)
@@ -49,19 +47,21 @@ importFrom(igraph,neighborhood.size)
 importFrom(igraph,page_rank)
 importFrom(igraph,vcount)
 importFrom(igraph,vertex)
+importFrom(knitr,knit_child)
 importFrom(knitr,opts_chunk)
 importFrom(magrittr,"%>%")
-importFrom(methods,formalArgs)
-importFrom(methods,hasArg)
 importFrom(methods,is)
 importFrom(rmarkdown,render)
 importFrom(tools,file_ext)
 importFrom(tools,file_path_as_absolute)
 importFrom(tools,package_dependencies)
 importFrom(utils,browseURL)
 importFrom(utils,installed.packages)
-importFrom(utils,lsf.str)
+importFrom(utils,packageDescription)
 importFrom(visNetwork,visEdges)
+importFrom(visNetwork,visGroups)
 importFrom(visNetwork,visHierarchicalLayout)
+importFrom(visNetwork,visIgraphLayout)
+importFrom(visNetwork,visLegend)
 importFrom(visNetwork,visNetwork)
 importFrom(visNetwork,visOptions)

R/AbstractGraphReporter.R

@@ -1,34 +1,69 @@
-#' @title Abstract Graph Reporter Class
-#' @name AbstractGraphReporter
-#' @description Defines the Abstract Class for all PackageGraphReporters defined in pkgnet.
-#'              The class is not meant to be instantiated, but inherited from and its methods
-#'              overloaded such that each Metric implements certain functionality.
-#' @family AbstractReporters
-#' @section Public Members:
+#' @title Network Reporters for Packages
+#' @name NetworkReporters
+#' @keywords internal
+#' @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.
+#'
+#'     This article describes the additional fields added by the
+#'     \code{AbstractGraphReporter} class definition.
+#'
+#' @section Public Methods:
 #' \describe{
-#'    \item{\code{edges}}{A data.table from SOURCE to TARGET nodes describing the connections}
-#'    \item{\code{nodes}}{A data.table with node as an identifier, and augmenting information about each node}
-#'    \item{\code{pkg_graph}}{An igraph object describing the package graph}
-#'    \item{\code{network_measures}}{A list of network measures calculated by \code{calculate_network_features}}
-#'    \item{\code{layout_type}}{Character string indicating currently active graph layout}
-#'    \item{\code{graph_viz}}{\code{visNetwork} object of package graph}
+#'     \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 Active Bindings:
+#' @section Public Fields:
 #' \describe{
-#'    \item{\code{pkg_graph}}{Returns the graph object}
-#'    \item{\code{network_measures}}{Returns a table of network measures, one row per node}
-#'    \item{\code{graph_viz}}{Returns the graph visualization object}
-#'    \item{\code{layout_type}}{If no value given, the current layout type for the graph visualization is returned.
-#'        If a valid layout type is given, this function will update the layout_type field.
-#'        You can use \code{grep("^layout_\\\\S", getNamespaceExports("igraph"), value = TRUE)} to see valid options.}
+#'     \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.
+#'     }
 #' }
-#' @importFrom data.table data.table copy uniqueN setkeyv
+NULL
+
+
 #' @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 methods hasArg formalArgs
-#' @importFrom visNetwork visNetwork visHierarchicalLayout visEdges visOptions
-#' @export
+#' @importFrom visNetwork visNetwork visIgraphLayout visEdges visOptions
+#' visGroups visLegend
 AbstractGraphReporter <- R6::R6Class(
     "AbstractGraphReporter"
     , inherit = AbstractPackageReporter

R/AbstractPackageReporter.R

@@ -1,35 +1,111 @@
-#' @title Abstract Package Reporter Class
-#' @name AbstractPackageReporter
-#' @family AbstractReporters
-#' @description Defines the Abstract Class for all PackageReporters defined in pkgnet.
-#'              The class is not meant to be instantiated, but inherited from and its methods
-#'              overloaded such that each Metric implements certain functionality.
-#' @importFrom R6 R6Class
-#' @importFrom tools file_path_as_absolute
-#' @importFrom utils installed.packages
+#' @title Package Reporters
+#' @name PackageReporters
+#' @keywords internal
+#' @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 all operations in the object are done for.}
+#'             \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}}: A string with the name of the package you are
-#'                   analyzing.}
-#'                 \item{\bold{\code{pkg_path}}: 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{\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 a particular reporters summary report on the package for use in a high level view}
-#'       }
+#'             \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
+#'                     }
+#'                 }
+#'             }
+#'         }
 #'     }
 #' }
-#' @export
+#'
+#' @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
+#' @importFrom utils installed.packages
 AbstractPackageReporter <- R6::R6Class(
     classname = "AbstractPackageReporter",
 

R/CreatePackageReport.R

@@ -1,17 +1,18 @@
-#' @title Surface the internal and external dependencies of an R package.
+#' @title pkgnet Analysis Report for an R package
 #' @name CreatePackageReport
-#' @description Surface the internal and external dependencies of an R package.
-#' @author B. Burns
-#' @seealso GetPackageGraphs
+#' @description Create a standalone HTML report about a package and its networks.
+#' @param pkg_name (string) name of a package
+#' @param pkg_path (string) The path to the package repository. If given, coverage
+#'                 will be calculated for each function. \code{pkg_path} can be an
+#'                 absolute or relative path.
 #' @param pkg_reporters (list) a list of package reporters
 #' @param report_path (string) The path and filename of the output report.  Default
 #'                   report will be produced in the temporary directory.
-#' @inheritParams doc_shared
 #' @importFrom assertthat assert_that is.readable is.string is.writeable
 #' @importFrom methods is
 #' @importFrom tools file_ext
 #' @importFrom utils browseURL
-#' @importFrom knitr opts_chunk
+#' @importFrom rmarkdown render
 #' @return A list of instantiated pkg_reporters fitted to \code{pkg_name}
 #' @export
 CreatePackageReport <- function(pkg_name
@@ -68,6 +69,9 @@ CreatePackageReport <- function(pkg_name
     return(invisible(builtReporters))
 }
 
+### Imports from package_report.Rmd
+#' @importFrom knitr opts_chunk knit_child
+NULL
 
 # [title] Package Report Renderer
 # [name] RenderPackageReport

R/DefaultReporters.R

@@ -1,6 +1,8 @@
 #' @title Default Reporters
 #' @name DefaultReporters
-#' @description Instantiates a list of default reporters to feed into \link{CreatePackageReport}
+#' @description Instantiates a list of default reporters to feed into
+#'    \code{\link{CreatePackageReport}}.
+#' @return list of instantiated reporter objects
 #' @export
 DefaultReporters <- function() {
     return(list(

R/GraphClasses.R

@@ -1,12 +1,12 @@
 #' @title Graph Classes for Network Modeling
 #' @name GraphClasses
-#' @rdname GraphClasses
 #' @description pkgnet uses R6 classes to define and encapsulate the graph
-#' models for representing package networks. These classes implement different
-#' types of graphs and functionality to calculate their respective graph theory
-#' measures.
+#'     models for representing package networks. These classes implement
+#'     different types of graphs and functionality to calculate their respective
+#'     graph theory measures. The base class \code{AbstractGraph} defines the
+#'     standard interfaces and functionality.
 #'
-#' Currently the only implemented type of graph is \link{DirectedGraph}
+#'     Currently the only implemented type of graph is \link{DirectedGraph}.
 #'
 #' @section Class Constructor:
 #' \describe{
@@ -294,16 +294,24 @@ AbstractGraph <- R6::R6Class(
 #' @title Directed Graph Network Model
 #' @name DirectedGraph
 #' @description R6 class defining a directed graph model for representing a
-#' network, including methods to calculate various measures from graph theory.
-#' The \link[igraph:igraph-package]{igraph} package is used as a backend for
-#' calculations.
-#' @format An \code{\link[R6]{R6Class}} generator object
-#' @inheritSection GraphClasses Class Constructor
+#'    network, including methods to calculate various measures from graph
+#'    theory. The \link[igraph:igraph-package]{igraph} package is used as a
+#'    backend for calculations.
+#'
+#'    This class isn't intended to be initialized directly; instead,
+#'    \link[=NetworkReporters]{network reporter objects} will initialize it as
+#'    its \code{pkg_graph} field. If you have a network reporter named
+#'    \code{reporter}, then you access this object's public
+#'    interface through \code{pkg_graph}---for example,
+#'
+#'    \preformatted{    reporter$pkg_graph$node_measures('hubScore')}
+#'
 #' @inheritSection GraphClasses Public Methods
 #' @inheritSection GraphClasses Public Fields
-#' @inheritSection GraphClasses Special Methods
 #' @inheritSection DirectedGraphMeasures Node Measures
 #' @inheritSection DirectedGraphMeasures Graph Measures
+NULL
+
 #' @importFrom R6 R6Class
 #' @importFrom igraph degree closeness betweenness
 #' @importFrom igraph page_rank hub_score authority_score
@@ -522,8 +530,9 @@ DirectedGraph <- R6::R6Class(
 
 #' @title Measures for Directed Graph Class
 #' @name DirectedGraphMeasures
-#' @rdname DirectedGraphMeasures
 #' @keywords internal
+#' @description Descriptions for all available node and graph measures for
+#'    networks modeled by \link{DirectedGraph}.
 #' @section Node Measures:
 #' \describe{
 #'     \item{\bold{\code{outDegree}}}{: outdegree, the number of outward edges (tail ends).