From 57999cc0b15c041dab097ee69e84f5f30d6a9e20 Mon Sep 17 00:00:00 2001 From: Jay Qi Date: Sun, 3 Mar 2019 13:06:53 -0600 Subject: [PATCH 1/3] Roxygen documentation overhaul --- NAMESPACE | 18 ++- R/AbstractGraphReporter.R | 83 ++++++++---- R/AbstractPackageReporter.R | 116 ++++++++++++++--- R/CreatePackageReport.R | 13 +- R/DefaultReporters.R | 4 +- R/GraphClasses.R | 33 +++-- R/PackageDependencyReporter.R | 35 +++-- R/PackageFunctionReporter.R | 106 ++++++++------- R/PackageInheritanceReporter.R | 37 +++--- R/PackageSummaryReporter.R | 55 ++++---- R/pkgnet.R | 72 ++++++++-- man/AbstractGraphReporter.Rd | 44 ------- man/AbstractPackageReporter.Rd | 45 ------- man/CreatePackageReport.Rd | 10 +- man/DefaultReporters.Rd | 6 +- man/DependencyReporter.Rd | 175 +++++++++++++++++++++++-- man/DirectedGraph.Rd | 71 ++-------- man/DirectedGraphMeasures.Rd | 3 +- man/FunctionReporter.Rd | 232 +++++++++++++++++++++++++++------ man/GraphClasses.Rd | 9 +- man/InheritanceReporter.Rd | 169 +++++++++++++++++++++--- man/NetworkReporters.Rd | 65 +++++++++ man/PackageReporters.Rd | 116 +++++++++++++++++ man/SummaryReporter.Rd | 119 +++++++++++++---- man/doc_shared.Rd | 16 --- man/pkgnet-package.Rd | 96 ++++++++++++++ 26 files changed, 1288 insertions(+), 460 deletions(-) delete mode 100644 man/AbstractGraphReporter.Rd delete mode 100644 man/AbstractPackageReporter.Rd create mode 100644 man/NetworkReporters.Rd create mode 100644 man/PackageReporters.Rd delete mode 100644 man/doc_shared.Rd create mode 100644 man/pkgnet-package.Rd diff --git a/NAMESPACE b/NAMESPACE index 16765a18..c8927324 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,7 +1,5 @@ # Generated by roxygen2: do not edit by hand -export(AbstractGraphReporter) -export(AbstractPackageReporter) export(CreatePackageReport) export(DefaultReporters) export(DependencyReporter) @@ -14,6 +12,7 @@ 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) @@ -21,18 +20,17 @@ 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,10 +47,7 @@ importFrom(igraph,neighborhood.size) importFrom(igraph,page_rank) importFrom(igraph,vcount) importFrom(igraph,vertex) -importFrom(knitr,opts_chunk) importFrom(magrittr,"%>%") -importFrom(methods,formalArgs) -importFrom(methods,hasArg) importFrom(methods,is) importFrom(rmarkdown,render) importFrom(tools,file_ext) @@ -60,8 +55,11 @@ 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) diff --git a/R/AbstractGraphReporter.R b/R/AbstractGraphReporter.R index 3f87a2f6..f4f119a2 100644 --- a/R/AbstractGraphReporter.R +++ b/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 diff --git a/R/AbstractPackageReporter.R b/R/AbstractPackageReporter.R index 4858dacd..e17ad4ba 100644 --- a/R/AbstractPackageReporter.R +++ b/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", diff --git a/R/CreatePackageReport.R b/R/CreatePackageReport.R index 3aff5c50..75ec2707 100644 --- a/R/CreatePackageReport.R +++ b/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 diff --git a/R/DefaultReporters.R b/R/DefaultReporters.R index 1a496def..a3166a1c 100644 --- a/R/DefaultReporters.R +++ b/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( diff --git a/R/GraphClasses.R b/R/GraphClasses.R index 0abff290..df3ff3f3 100644 --- a/R/GraphClasses.R +++ b/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). diff --git a/R/PackageDependencyReporter.R b/R/PackageDependencyReporter.R index 5fcebddd..970db85c 100644 --- a/R/PackageDependencyReporter.R +++ b/R/PackageDependencyReporter.R @@ -1,15 +1,19 @@ -#' @title Package Dependency Reporter Class +#' @title Recursive Package Dependency Reporter #' @name DependencyReporter -#' @family PackageReporters -#' @description This Reporter takes a package and uncovers the structure from -#' its other package dependencies, determining which package it relies on is most central, -#' allowing for a developer to determine how to vet its dependency tree -#' @importFrom data.table data.table setnames rbindlist -#' @importFrom R6 R6Class -#' @importFrom utils installed.packages -#' @importFrom tools package_dependencies -#' @importFrom data.table data.table rbindlist setkeyv -#' @export +#' @family Network Reporters +#' @family Package Reporters +#' @description This reporter looks at the recursive network of its dependencies +#' on other packages. This allows a developer to understand how individual +#' dependencies might lead to a much larger set of dependencies, potentially +#' informing decisions on including or removing them. +#' @section Class Constructor: +#' \preformatted{DependencyReporter$new()} +#' @inheritSection PackageReporters Class Constructor +#' @inheritSection PackageReporters Public Methods +#' @inheritSection NetworkReporters Public Methods +#' @inheritSection PackageReporters Public Fields +#' @inheritSection NetworkReporters Public Fields +#' @inheritSection PackageReporters Special Methods #' @examples #' \donttest{ #' @@ -22,6 +26,15 @@ #' # plot it up #' reporter$plot_network() #' } +NULL + +#' @importFrom R6 R6Class +#' @importFrom assertthat assert_that is.flag +#' @importFrom utils installed.packages +#' @importFrom tools package_dependencies +#' @importFrom data.table data.table rbindlist setkeyv +#' @importFrom visNetwork visHierarchicalLayout +#' @export DependencyReporter <- R6::R6Class( "DependencyReporter", inherit = AbstractGraphReporter, diff --git a/R/PackageFunctionReporter.R b/R/PackageFunctionReporter.R index 78f6b3a2..76fc8c80 100644 --- a/R/PackageFunctionReporter.R +++ b/R/PackageFunctionReporter.R @@ -1,55 +1,69 @@ -#' @title Package Function Reporter Class +#' @title Function Interdependency Reporter #' @name FunctionReporter -#' @family PackageReporters -#' @description This Reporter takes a package and uncovers the structure from -#' its other functions, determining useful information such as which function is most -#' central to the package. Combined with testing information it can be used as a powerful tool -#' to plan testing efforts. +#' @family Network Reporters +#' @family Package Reporters +#' @description This reporter looks at the network of interdependencies of its +#' defined functions. Measures of centrality from graph theory can indicate +#' which function is most important to a package. Combined with unit test +#' coverage information---also provided by this reporter--- it can be used +#' as a powerful tool to prioritize test writing. +#' @section Class Constructor: +#' \preformatted{FunctionReporter$new()} +#' @inheritSection PackageReporters Class Constructor +#' @inheritSection PackageReporters Public Methods +#' @inheritSection NetworkReporters Public Methods +#' @inheritSection PackageReporters Public Fields +#' @inheritSection NetworkReporters Public Fields +#' @inheritSection PackageReporters Special Methods +#' @details +#' \subsection{R6 Method Support:}{ +#' R6 classes are supported, with their methods treated as functions by the +#' reporter. #' -#' R6 classes are supported, with methods treated as functions by the Reporter. -#' R6 methods will be named like \code{$$} -#' , e.g., \code{FunctionReporter$private_methods$extract_nodes}. Note that the -#' class name used will be the \emph{name of the generator object in the package's namespace}, -#' and \emph{not} the \code{classname} attribute of the class, which is not required to be defined -#' or to be the same as the generator object name. -#' -#' @section Public Methods: -#' \describe{ -#' \item{\code{set_package(pkg_name, pkg_path)}}{ -#' \itemize{ -#' \item{Set properties of this reporter. If pkg_name overrides a -#' previously-set package name, any cached data will be removed.} -#' \item{\bold{Args:}}{ -#' \itemize{ -#' \item{\bold{\code{pkg_name}}: String with the name of the package.} -#' \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.} -#' } -#' } -#' } -#' } +#' \itemize{ +#' \item{R6 methods will be named like +#' \code{$$}, e.g., +#' \code{FunctionReporter$private_methods$extract_nodes}. +#' } +#' \item{Note that the class name used will be the \strong{name of the +#' generator object in the package's namespace}. +#' } +#' \item{The \code{classname} attribute of the class is \strong{not} used. +#' In general, it is not required to be defined or the same as the +#' generator object name. This attribute is used primarily for +#' S3 dispatch. +#' } +#' } #' } -#' @section Known Limitations: -#' \itemize{ -#' \item{Using non-standard evaluation to refer to things (e.g, dataframe column names) -#' that have the same name as a function will trick \code{FunctionReporter} into thinking -#' the function was called. This can be avoided if you don't use reuse function names -#' for other purposes.} -#' \item{Functions stored as list items and not assigned to the package namespace -#' will be invisible to \code{FunctionReporter}.} -#' \item{Calls to methods of instantiated R6 or reference objects will not be recognized. -#' We don't have a reliable way of identifying instantiated objects, or identifying -#' their class.} -#' \item{Reference class methods are not yet supported. They will not be idenified -#' as nodes by \code{FunctionReporter}.} +#' \subsection{Known Limitations:}{ +#' \itemize{ +#' \item{Using non-standard evaluation to refer to things (e.g, dataframe +#' column names) that have the same name as a function will trick +#' \code{FunctionReporter} into thinking the function was called. This +#' can be avoided if you don't use reuse function names for other +#' purposes. +#' } +#' \item{Functions stored as list items and not assigned to the package +#' namespace will be invisible to \code{FunctionReporter}. +#' } +#' \item{Calls to methods of instantiated R6 or reference objects will +#' not be recognized. We don't have a reliable way of identifying +#' instantiated objects, or identifying their class. +#' } +#' \item{Reference class methods are not yet supported. They will not be +#' identified as nodes by \code{FunctionReporter}. +#' } +#' } #' } +NULL + + +#' @importFrom R6 R6Class is.R6Class +#' @importFrom assertthat assert_that is.string #' @importFrom covr package_coverage -#' @importFrom data.table data.table melt as.data.table data.table setnames -#' setcolorder rbindlist setkeyv -#' @importFrom R6 R6Class -#' @importFrom utils lsf.str +#' @importFrom data.table data.table as.data.table rbindlist setkeyv #' @importFrom methods is +#' @importFrom visNetwork visHierarchicalLayout #' @export FunctionReporter <- R6::R6Class( "FunctionReporter", diff --git a/R/PackageInheritanceReporter.R b/R/PackageInheritanceReporter.R index 68de5ebe..3a736a0a 100644 --- a/R/PackageInheritanceReporter.R +++ b/R/PackageInheritanceReporter.R @@ -1,6 +1,7 @@ -#' @title Package Class Inheritance Reporter Class +#' @title Class Inheritance Reporter #' @name InheritanceReporter -#' @family PackageReporters +#' @family Network Reporters +#' @family Package Reporters #' @description This reporter takes a package and traces the class inheritance #' structure. Currently the following object-oriented systems are supported: #' \itemize{ @@ -10,8 +11,15 @@ #' } #' S3 classes are not supported, as their inheritance is defined on an ad hoc #' basis per object and not formally by class definitions. -#' -#' Note the following details about class naming: +#' @section Class Constructor: +#' \preformatted{InheritanceReporter$new()} +#' @inheritSection PackageReporters Class Constructor +#' @inheritSection PackageReporters Public Methods +#' @inheritSection NetworkReporters Public Methods +#' @inheritSection PackageReporters Public Fields +#' @inheritSection NetworkReporters Public Fields +#' @inheritSection PackageReporters Special Methods +#' @details Note the following details about class naming: #' \itemize{ #' \item{Reference Classes : The name passed as \code{Class} in #' \code{\link[methods:ReferenceClasses]{setRefClass}} is used as the node @@ -32,27 +40,12 @@ #' Wickham's \emph{Advanced R}}. For more info about R6, check out their #' \href{https://r6.r-lib.org/index.html}{docs website} or the chapter in #' \href{https://adv-r.hadley.nz/r6.html}{\emph{Advanced R}'s second edition}. -#' -#' @section Public Methods: -#' \describe{ -#' \item{\code{set_package(pkg_name, pkg_path)}}{ -#' \itemize{ -#' \item{Set properties of this reporter. If pkg_name overrides a -#' previously-set package name, any cached data will be removed.} -#' \item{\bold{Args:}}{ -#' \itemize{ -#' \item{\bold{\code{pkg_name}}: String with the name of the package.} -#' \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.} -#' } -#' } -#' } -#' } -#' } +NULL + #' @importFrom R6 R6Class is.R6Class #' @importFrom data.table data.table rbindlist setkeyv #' @importFrom methods is +#' @importFrom visNetwork visHierarchicalLayout #' @export InheritanceReporter <- R6::R6Class( "InheritanceReporter" diff --git a/R/PackageSummaryReporter.R b/R/PackageSummaryReporter.R index 01ddc8ec..4be36ea5 100644 --- a/R/PackageSummaryReporter.R +++ b/R/PackageSummaryReporter.R @@ -1,12 +1,21 @@ -#' @title Package Summary Reporter Class +#' @title Package Summary Reporter #' @name SummaryReporter -#' @family PackageReporters -#' @description Defines a concrete implementation of \link{AbstractPackageReporter} -#' for a high level overview of a particular package. It will summarize -#' things like lines of code, whether it's on CRAN, etc. -#' @inheritSection AbstractPackageReporter Public Methods -#' @importFrom DT datatable +#' @family Package Reporters +#' @description This reporter provides a high-level overview of a package via +#' its package DESCRIPTION file. +#' @section Class Constructor: +#' \preformatted{SummaryReporter$new()} +#' @inheritSection PackageReporters Class Constructor +#' @inheritSection PackageReporters Public Methods +#' @inheritSection PackageReporters Public Fields +#' @inheritSection PackageReporters Special Methods +NULL + + #' @importFrom R6 R6Class +#' @importFrom utils packageDescription +#' @importFrom data.table data.table +#' @importFrom DT datatable #' @export SummaryReporter <- R6::R6Class( classname = "SummaryReporter", @@ -14,24 +23,24 @@ SummaryReporter <- R6::R6Class( public = list( get_summary_view = function(){ - # Read DESCRIPTION file into a table - desc <- utils::packageDescription(self$pkg_name) - descDT <- data.table::data.table( - Field = names(desc) - , Values = unlist(desc) - ) + # Read DESCRIPTION file into a table + desc <- utils::packageDescription(self$pkg_name) + descDT <- data.table::data.table( + Field = names(desc) + , Values = unlist(desc) + ) - # Render DT table - tableObj <- DT::datatable( - data = descDT - , rownames = FALSE - , options = list( - searching = FALSE - , pageLength = 50 - , lengthChange = FALSE + # Render DT table + tableObj <- DT::datatable( + data = descDT + , rownames = FALSE + , options = list( + searching = FALSE + , pageLength = 50 + , lengthChange = FALSE + ) ) - ) - return(tableObj) + return(tableObj) } ), diff --git a/R/pkgnet.R b/R/pkgnet.R index a82ba5aa..c859463f 100644 --- a/R/pkgnet.R +++ b/R/pkgnet.R @@ -33,14 +33,66 @@ globalVariables(c('.' , 'SYMBOL' )) -# NULL object for common parameter documentation -#' @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. -#' @name doc_shared -#' @title NULL Object For Common Documentation -#' @description This is a NULL object with documentation so that later functions can call -#' inheritParams -NULL +#' @title pkgnet : Network Analysis of R Packages +#' @keywords internal +#' @description R packages can be complex bodies of code and functionality with +#' hard-to-intuit underlying structure. \pkg{pkgnet} provides tools to analyze and +#' understand that structure through the lens of +#' \href{https://en.wikipedia.org/wiki/Network_theory}{network theory}. +#' +#' @section Package Report: +#' The simplest way of using pkgnet is through the function +#' \code{\link{CreatePackageReport}}, e.g., +#' +#' \preformatted{ CreatePackageReport("lubridate")} +#' +#' This will create a standalone HTML report containing analyses of various +#' aspects of the specified subject package. +#' +#' For more info, check out our introductory vignette with +#' +#' \preformatted{ vignette("pkgnet-intro")} +#' +#' @section Individual Reporters: +#' Reporters are the basic modules of functionality within pkgnet. Each +#' type of reporter is used to analyze a particular aspect of the subject +#' package. The currently available reporters are: +#' +#' \describe{ +#' \item{\bold{\code{\link{DependencyReporter}}}}{: analyze the recursive +#' network of packages that the subject package depends on. +#' } +#' \item{\bold{\code{\link{FunctionReporter}}}}{: analyze the network of +#' interdependencies of the functions defined in the subject package +#' } +#' \item{\bold{\code{\link{InheritanceReporter}}}}{: analyze the class +#' inheritance trees for subject packages that use object-oriented +#' programming. +#' } +#' \item{\bold{\code{\link{SummaryReporter}}}}{: get an overview of the +#' subject package through its DESCRIPTION file. +#' } +#' } +#' +#' \code{\link{CreatePackageReport}} uses a \link[=DefaultReporters]{standard +#' set of reporters} by default. You can customize the reporters you want by +#' passing in your own list of instantiated reporters, e.g. +#' +#' \preformatted{ +#' CreatePackageReport( +#' "lubridate", +#' pkg_reporters = list(FunctionReporter$new(), InheritanceReporter$new()) +#' ) +#' } +#' +#' You can also use reporters interactively. Once you have a reporter +#' instantiated, check our that reporter's documentation to see what you can +#' do. +#' +#' \preformatted{ +#' reporter <- DependencyReporter$new() +#' reporter$set_package("lubridate") +#' } +#' +"_PACKAGE" diff --git a/man/AbstractGraphReporter.Rd b/man/AbstractGraphReporter.Rd deleted file mode 100644 index 560506db..00000000 --- a/man/AbstractGraphReporter.Rd +++ /dev/null @@ -1,44 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/AbstractGraphReporter.R -\docType{data} -\name{AbstractGraphReporter} -\alias{AbstractGraphReporter} -\title{Abstract Graph Reporter Class} -\format{An object of class \code{R6ClassGenerator} of length 24.} -\usage{ -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. -} -\section{Public Members}{ - -\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} -} -} - -\section{Active Bindings}{ - -\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.} -} -} - -\seealso{ -Other AbstractReporters: \code{\link{AbstractPackageReporter}} -} -\concept{AbstractReporters} -\keyword{datasets} diff --git a/man/AbstractPackageReporter.Rd b/man/AbstractPackageReporter.Rd deleted file mode 100644 index b9b624bc..00000000 --- a/man/AbstractPackageReporter.Rd +++ /dev/null @@ -1,45 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/AbstractPackageReporter.R -\docType{data} -\name{AbstractPackageReporter} -\alias{AbstractPackageReporter} -\title{Abstract Package Reporter Class} -\format{An object of class \code{R6ClassGenerator} of length 24.} -\usage{ -AbstractPackageReporter -} -\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. -} -\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{\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{\code{get_summary_view()}}{ - \itemize{ - \item{Returns a particular reporters summary report on the package for use in a high level view} - } - } -} -} - -\seealso{ -Other AbstractReporters: \code{\link{AbstractGraphReporter}} -} -\concept{AbstractReporters} -\keyword{datasets} diff --git a/man/CreatePackageReport.Rd b/man/CreatePackageReport.Rd index 7603e978..e40754cb 100644 --- a/man/CreatePackageReport.Rd +++ b/man/CreatePackageReport.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/CreatePackageReport.R \name{CreatePackageReport} \alias{CreatePackageReport} -\title{Surface the internal and external dependencies of an R package.} +\title{pkgnet Analysis Report for an R package} \usage{ CreatePackageReport(pkg_name, pkg_reporters = DefaultReporters(), pkg_path = NULL, report_path = tempfile(pattern = pkg_name, fileext = @@ -24,11 +24,5 @@ report will be produced in the temporary directory.} A list of instantiated pkg_reporters fitted to \code{pkg_name} } \description{ -Surface the internal and external dependencies of an R package. -} -\seealso{ -GetPackageGraphs -} -\author{ -B. Burns +Create a standalone HTML report about a package and its networks. } diff --git a/man/DefaultReporters.Rd b/man/DefaultReporters.Rd index 639cee6a..bbc2e1ef 100644 --- a/man/DefaultReporters.Rd +++ b/man/DefaultReporters.Rd @@ -6,6 +6,10 @@ \usage{ DefaultReporters() } +\value{ +list of instantiated reporter objects +} \description{ -Instantiates a list of default reporters to feed into \link{CreatePackageReport} +Instantiates a list of default reporters to feed into + \code{\link{CreatePackageReport}}. } diff --git a/man/DependencyReporter.Rd b/man/DependencyReporter.Rd index b0dc547e..7d053d25 100644 --- a/man/DependencyReporter.Rd +++ b/man/DependencyReporter.Rd @@ -1,18 +1,166 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/PackageDependencyReporter.R -\docType{data} \name{DependencyReporter} \alias{DependencyReporter} -\title{Package Dependency Reporter Class} -\format{An object of class \code{R6ClassGenerator} of length 24.} -\usage{ -DependencyReporter -} +\title{Recursive Package Dependency Reporter} \description{ -This Reporter takes a package and uncovers the structure from - its other package dependencies, determining which package it relies on is most central, - allowing for a developer to determine how to vet its dependency tree +This reporter looks at the recursive network of its dependencies + on other packages. This allows a developer to understand how individual + dependencies might lead to a much larger set of dependencies, potentially + informing decisions on including or removing them. +} +\section{Class Constructor}{ + +\preformatted{DependencyReporter$new()} + + +\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 + } + } + } + } + } +} + + +\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{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. + } +} + + +\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. + } +} +} + +\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.} + } + } + } + } +} +} + \examples{ \donttest{ @@ -27,9 +175,12 @@ reporter$plot_network() } } \seealso{ -Other PackageReporters: \code{\link{FunctionReporter}}, +Other Network Reporters: \code{\link{FunctionReporter}}, + \code{\link{InheritanceReporter}} + +Other Package Reporters: \code{\link{FunctionReporter}}, \code{\link{InheritanceReporter}}, \code{\link{SummaryReporter}} } -\concept{PackageReporters} -\keyword{datasets} +\concept{Network Reporters} +\concept{Package Reporters} diff --git a/man/DirectedGraph.Rd b/man/DirectedGraph.Rd index 57bf5a08..d5a25696 100644 --- a/man/DirectedGraph.Rd +++ b/man/DirectedGraph.Rd @@ -1,41 +1,22 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/GraphClasses.R -\docType{data} \name{DirectedGraph} \alias{DirectedGraph} \title{Directed Graph Network Model} -\format{An \code{\link[R6]{R6Class}} generator object} -\usage{ -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. -} -\section{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. -\describe{ - \item{\code{new(nodes, edges)}}{ - \itemize{ - \item{Instantiate new object of the class.} - \item{\bold{Args:}}{ - \itemize{ - \item{\bold{\code{nodes}}: a data.table containing nodes} - \item{\bold{\code{edges}}: a data.table containing edges} - } - } - \item{\bold{Returns:}}{ - \itemize{ - \item{Object of the class} - } - } - } - } -} -} + 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')} +} \section{Public Methods}{ \describe{ @@ -99,37 +80,6 @@ calculations. } } -\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.} - } - } - } - } - \item{\code{print()}}{ - \itemize{ - \item{Print igraph object.} - \item{\bold{Returns:}}{ - \itemize{ - \item{Self} - } - } - } - } -} -} - \section{Node Measures}{ \describe{ @@ -204,4 +154,3 @@ calculations. } } -\keyword{datasets} diff --git a/man/DirectedGraphMeasures.Rd b/man/DirectedGraphMeasures.Rd index 5954f64d..15409974 100644 --- a/man/DirectedGraphMeasures.Rd +++ b/man/DirectedGraphMeasures.Rd @@ -4,7 +4,8 @@ \alias{DirectedGraphMeasures} \title{Measures for Directed Graph Class} \description{ -Measures for Directed Graph Class +Descriptions for all available node and graph measures for + networks modeled by \link{DirectedGraph}. } \section{Node Measures}{ diff --git a/man/FunctionReporter.Rd b/man/FunctionReporter.Rd index b78ba7da..03715e3b 100644 --- a/man/FunctionReporter.Rd +++ b/man/FunctionReporter.Rd @@ -1,67 +1,215 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/PackageFunctionReporter.R -\docType{data} \name{FunctionReporter} \alias{FunctionReporter} -\title{Package Function Reporter Class} -\format{An object of class \code{R6ClassGenerator} of length 24.} -\usage{ -FunctionReporter -} +\title{Function Interdependency Reporter} \description{ -This Reporter takes a package and uncovers the structure from - its other functions, determining useful information such as which function is most - central to the package. Combined with testing information it can be used as a powerful tool - to plan testing efforts. - -R6 classes are supported, with methods treated as functions by the Reporter. -R6 methods will be named like \code{$$} -, e.g., \code{FunctionReporter$private_methods$extract_nodes}. Note that the -class name used will be the \emph{name of the generator object in the package's namespace}, -and \emph{not} the \code{classname} attribute of the class, which is not required to be defined -or to be the same as the generator object name. +This reporter looks at the network of interdependencies of its + defined functions. Measures of centrality from graph theory can indicate + which function is most important to a package. Combined with unit test + coverage information---also provided by this reporter--- it can be used + as a powerful tool to prioritize test writing. +} +\details{ +\subsection{R6 Method Support:}{ + R6 classes are supported, with their methods treated as functions by the + reporter. + + \itemize{ + \item{R6 methods will be named like + \code{$$}, e.g., + \code{FunctionReporter$private_methods$extract_nodes}. + } + \item{Note that the class name used will be the \strong{name of the + generator object in the package's namespace}. + } + \item{The \code{classname} attribute of the class is \strong{not} used. + In general, it is not required to be defined or the same as the + generator object name. This attribute is used primarily for + S3 dispatch. + } + } +} +\subsection{Known Limitations:}{ + \itemize{ + \item{Using non-standard evaluation to refer to things (e.g, dataframe + column names) that have the same name as a function will trick + \code{FunctionReporter} into thinking the function was called. This + can be avoided if you don't use reuse function names for other + purposes. + } + \item{Functions stored as list items and not assigned to the package + namespace will be invisible to \code{FunctionReporter}. + } + \item{Calls to methods of instantiated R6 or reference objects will + not be recognized. We don't have a reliable way of identifying + instantiated objects, or identifying their class. + } + \item{Reference class methods are not yet supported. They will not be + identified as nodes by \code{FunctionReporter}. + } + } +} } +\section{Class Constructor}{ + +\preformatted{FunctionReporter$new()} + + +\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)}}{ + \item{\code{set_package(pkg_name, pkg_path = NULL)}}{ \itemize{ - \item{Set properties of this reporter. If pkg_name overrides a - previously-set package name, any cached data will be removed.} + \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}}: String with the name of the package.} - \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 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 + } + } } } } } + + +\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{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. + } +} + + +\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. + } +} } -\section{Known Limitations}{ - -\itemize{ - \item{Using non-standard evaluation to refer to things (e.g, dataframe column names) - that have the same name as a function will trick \code{FunctionReporter} into thinking - the function was called. This can be avoided if you don't use reuse function names - for other purposes.} - \item{Functions stored as list items and not assigned to the package namespace - will be invisible to \code{FunctionReporter}.} - \item{Calls to methods of instantiated R6 or reference objects will not be recognized. - We don't have a reliable way of identifying instantiated objects, or identifying - their class.} - \item{Reference class methods are not yet supported. They will not be idenified - as nodes by \code{FunctionReporter}.} +\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.} + } + } + } + } } } \seealso{ -Other PackageReporters: \code{\link{DependencyReporter}}, +Other Network Reporters: \code{\link{DependencyReporter}}, + \code{\link{InheritanceReporter}} + +Other Package Reporters: \code{\link{DependencyReporter}}, \code{\link{InheritanceReporter}}, \code{\link{SummaryReporter}} } -\concept{PackageReporters} -\keyword{datasets} +\concept{Network Reporters} +\concept{Package Reporters} diff --git a/man/GraphClasses.Rd b/man/GraphClasses.Rd index 9a5a6f7d..e5e6a433 100644 --- a/man/GraphClasses.Rd +++ b/man/GraphClasses.Rd @@ -5,11 +5,12 @@ \title{Graph Classes for Network Modeling} \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}{ diff --git a/man/InheritanceReporter.Rd b/man/InheritanceReporter.Rd index 14a68936..8c842f2e 100644 --- a/man/InheritanceReporter.Rd +++ b/man/InheritanceReporter.Rd @@ -1,13 +1,8 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/PackageInheritanceReporter.R -\docType{data} \name{InheritanceReporter} \alias{InheritanceReporter} -\title{Package Class Inheritance Reporter Class} -\format{An object of class \code{R6ClassGenerator} of length 24.} -\usage{ -InheritanceReporter -} +\title{Class Inheritance Reporter} \description{ This reporter takes a package and traces the class inheritance structure. Currently the following object-oriented systems are supported: @@ -18,8 +13,9 @@ This reporter takes a package and traces the class inheritance } S3 classes are not supported, as their inheritance is defined on an ad hoc basis per object and not formally by class definitions. - - Note the following details about class naming: +} +\details{ +Note the following details about class naming: \itemize{ \item{Reference Classes : The name passed as \code{Class} in \code{\link[methods:ReferenceClasses]{setRefClass}} is used as the node @@ -41,20 +37,152 @@ This reporter takes a package and traces the class inheritance \href{https://r6.r-lib.org/index.html}{docs website} or the chapter in \href{https://adv-r.hadley.nz/r6.html}{\emph{Advanced R}'s second edition}. } +\section{Class Constructor}{ + +\preformatted{InheritanceReporter$new()} + + +\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)}}{ + \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 + } + } + } + } + } +} + + +\describe{ + \item{\code{calculate_default_measures()}}{ \itemize{ - \item{Set properties of this reporter. If pkg_name overrides a - previously-set package name, any cached data will be removed.} + \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{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. + } +} + + +\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. + } +} +} + +\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{pkg_name}}: String with the name of the package.} - \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{deep}}: logical. Whether to recursively + clone nested R6 objects. + } + } + } + \item{\bold{Returns:}}{ + \itemize{ + \item{Cloned object of this class.} + } } } } @@ -62,9 +190,12 @@ This reporter takes a package and traces the class inheritance } \seealso{ -Other PackageReporters: \code{\link{DependencyReporter}}, +Other Network Reporters: \code{\link{DependencyReporter}}, + \code{\link{FunctionReporter}} + +Other Package Reporters: \code{\link{DependencyReporter}}, \code{\link{FunctionReporter}}, \code{\link{SummaryReporter}} } -\concept{PackageReporters} -\keyword{datasets} +\concept{Network Reporters} +\concept{Package Reporters} diff --git a/man/NetworkReporters.Rd b/man/NetworkReporters.Rd new file mode 100644 index 00000000..53c89bba --- /dev/null +++ b/man/NetworkReporters.Rd @@ -0,0 +1,65 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/AbstractGraphReporter.R +\name{NetworkReporters} +\alias{NetworkReporters} +\title{Network Reporters for Packages} +\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{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. + } +} +} + +\keyword{internal} diff --git a/man/PackageReporters.Rd b/man/PackageReporters.Rd new file mode 100644 index 00000000..187606c6 --- /dev/null +++ b/man/PackageReporters.Rd @@ -0,0 +1,116 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/AbstractPackageReporter.R +\name{PackageReporters} +\alias{PackageReporters} +\title{Package 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.} + } + } + } + } +} +} + +\keyword{internal} diff --git a/man/SummaryReporter.Rd b/man/SummaryReporter.Rd index 69b219ac..07a4a954 100644 --- a/man/SummaryReporter.Rd +++ b/man/SummaryReporter.Rd @@ -1,47 +1,122 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/PackageSummaryReporter.R -\docType{data} \name{SummaryReporter} \alias{SummaryReporter} -\title{Package Summary Reporter Class} -\format{An object of class \code{R6ClassGenerator} of length 24.} -\usage{ -SummaryReporter -} +\title{Package Summary Reporter} \description{ -Defines a concrete implementation of \link{AbstractPackageReporter} - for a high level overview of a particular package. It will summarize - things like lines of code, whether it's on CRAN, etc. +This reporter provides a high-level overview of a package via + its package DESCRIPTION file. +} +\section{Class Constructor}{ + +\preformatted{SummaryReporter$new()} + + +\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 + } + } + } + } + } +} +} + +\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.} + } + } + } } } } \seealso{ -Other PackageReporters: \code{\link{DependencyReporter}}, +Other Package Reporters: \code{\link{DependencyReporter}}, \code{\link{FunctionReporter}}, \code{\link{InheritanceReporter}} } -\concept{PackageReporters} -\keyword{datasets} +\concept{Package Reporters} diff --git a/man/doc_shared.Rd b/man/doc_shared.Rd deleted file mode 100644 index cb82a9e0..00000000 --- a/man/doc_shared.Rd +++ /dev/null @@ -1,16 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/pkgnet.R -\name{doc_shared} -\alias{doc_shared} -\title{NULL Object For Common Documentation} -\arguments{ -\item{pkg_name}{(string) name of a package} - -\item{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.} -} -\description{ -This is a NULL object with documentation so that later functions can call -inheritParams -} diff --git a/man/pkgnet-package.Rd b/man/pkgnet-package.Rd new file mode 100644 index 00000000..a305abcc --- /dev/null +++ b/man/pkgnet-package.Rd @@ -0,0 +1,96 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/pkgnet.R +\docType{package} +\name{pkgnet-package} +\alias{pkgnet} +\alias{pkgnet-package} +\title{pkgnet : Network Analysis of R Packages} +\description{ +R packages can be complex bodies of code and functionality with + hard-to-intuit underlying structure. \pkg{pkgnet} provides tools to analyze and + understand that structure through the lens of + \href{https://en.wikipedia.org/wiki/Network_theory}{network theory}. +} +\section{Package Report}{ + + The simplest way of using pkgnet is through the function + \code{\link{CreatePackageReport}}, e.g., + + \preformatted{ CreatePackageReport("lubridate")} + + This will create a standalone HTML report containing analyses of various + aspects of the specified subject package. + + For more info, check out our introductory vignette with + + \preformatted{ vignette("pkgnet-intro")} +} + +\section{Individual Reporters}{ + + Reporters are the basic modules of functionality within pkgnet. Each + type of reporter is used to analyze a particular aspect of the subject + package. The currently available reporters are: + + \describe{ + \item{\bold{\code{\link{DependencyReporter}}}}{: analyze the recursive + network of packages that the subject package depends on. + } + \item{\bold{\code{\link{FunctionReporter}}}}{: analyze the network of + interdependencies of the functions defined in the subject package + } + \item{\bold{\code{\link{InheritanceReporter}}}}{: analyze the class + inheritance trees for subject packages that use object-oriented + programming. + } + \item{\bold{\code{\link{SummaryReporter}}}}{: get an overview of the + subject package through its DESCRIPTION file. + } + } + + \code{\link{CreatePackageReport}} uses a \link[=DefaultReporters]{standard + set of reporters} by default. You can customize the reporters you want by + passing in your own list of instantiated reporters, e.g. + + \preformatted{ + CreatePackageReport( + "lubridate", + pkg_reporters = list(FunctionReporter$new(), InheritanceReporter$new()) + ) + } + + You can also use reporters interactively. Once you have a reporter + instantiated, check our that reporter's documentation to see what you can + do. + + \preformatted{ + reporter <- DependencyReporter$new() + reporter$set_package("lubridate") + } +} + +\seealso{ +Useful links: +\itemize{ + \item \url{https://github.com/UptakeOpenSource/pkgnet} + \item \url{https://uptakeopensource.github.io/pkgnet/} + \item Report bugs at \url{https://github.com/UptakeOpenSource/pkgnet/issues} +} + +} +\author{ +\strong{Maintainer}: Brian Burns \email{brian.burns@uptake.com} + +Authors: +\itemize{ + \item James Lamb \email{james.lamb@uptake.com} + \item Jay Qi \email{jay.qi@uptake.com} +} + +Other contributors: +\itemize{ + \item Patrick Boueri \email{patrick.boueri@uptake.com} [contributor] +} + +} +\keyword{internal} From 84bfc58d761989dd73b30c78bf661190a83e91ae Mon Sep 17 00:00:00 2001 From: Jay Qi Date: Sun, 3 Mar 2019 13:25:43 -0600 Subject: [PATCH 2/3] Update unit tests for Abstract classes being unexported --- tests/testthat/test-AbstractGraphReporter.R | 12 ++++++------ tests/testthat/test-AbstractPackageReporter.R | 13 ++++++------- 2 files changed, 12 insertions(+), 13 deletions(-) diff --git a/tests/testthat/test-AbstractGraphReporter.R b/tests/testthat/test-AbstractGraphReporter.R index e576afae..d9a44d7b 100644 --- a/tests/testthat/test-AbstractGraphReporter.R +++ b/tests/testthat/test-AbstractGraphReporter.R @@ -28,7 +28,7 @@ test_that('AbstractGraphReporter public interface is as expected', { , "report_markdown_path" ) - reporter <- pkgnet::AbstractGraphReporter$new() + reporter <- pkgnet:::AbstractGraphReporter$new() expect_setequal(object = names(reporter) , expected = publicInterfaceExpected) }) @@ -36,31 +36,31 @@ test_that('AbstractGraphReporter public interface is as expected', { test_that("AbstractGraphReporter layout type setting works", { expect_equal( object = { - x <- AbstractGraphReporter$new() + x <- pkgnet:::AbstractGraphReporter$new() x$layout_type <- pkgnet:::.igraphAvailableLayouts()[[1]] x$layout_type } , expected = pkgnet:::.igraphAvailableLayouts()[[1]] ) expect_error({ - x <- AbstractGraphReporter$new() + x <- pkgnet:::AbstractGraphReporter$new() x$layout_type <- 'layout_as_newspaper' }, regexp = "layout_as_newspaper is not a supported layout by igraph") }) test_that("AbstractGraphReporter errors on unimplemented methods", { expect_error({ - x <- AbstractGraphReporter$new() + x <- pkgnet:::AbstractGraphReporter$new() x$nodes }, regexp = "Node extraction not implemented for this reporter") expect_error({ - x <- AbstractGraphReporter$new() + x <- pkgnet:::AbstractGraphReporter$new() x$edges }, regexp = "Edge extraction not implemented for this reporter") expect_error({ - x <- AbstractGraphReporter$new() + x <- pkgnet:::AbstractGraphReporter$new() x$pkg_graph }, regexp = "Reporter must set valid graph class") }) diff --git a/tests/testthat/test-AbstractPackageReporter.R b/tests/testthat/test-AbstractPackageReporter.R index 1052c914..53949ea3 100644 --- a/tests/testthat/test-AbstractPackageReporter.R +++ b/tests/testthat/test-AbstractPackageReporter.R @@ -19,7 +19,7 @@ test_that('AbstractPackageReporter public interface is as expected', { , "report_markdown_path" ) - reporter <- pkgnet::AbstractPackageReporter$new() + reporter <- pkgnet:::AbstractPackageReporter$new() expect_setequal(object = names(reporter) , expected = publicInterfaceExpected) }) @@ -27,7 +27,7 @@ test_that('AbstractPackageReporter public interface is as expected', { test_that("AbstractPackageReporter does not let you set_package twice", { expect_error({ - x <- AbstractPackageReporter$new() + x <- pkgnet:::AbstractPackageReporter$new() x$set_package("baseballstats") x$set_package("baseballstats") }, regexp = "A package has already been set for this reporter") @@ -35,26 +35,26 @@ test_that("AbstractPackageReporter does not let you set_package twice", { test_that("AbstractPackageReporter rejects bad packages with an informative error", { expect_error({ - x <- AbstractPackageReporter$new() + x <- pkgnet:::AbstractPackageReporter$new() x$set_package("w0uldNEverB33aPackageName") }, regexp = "pkgnet could not find a package called 'w0uldNEverB33aPackageName'") }) test_that("AbstractPackageReporter rejects bad pkg_path with an informative error", { expect_error({ - x <- AbstractPackageReporter$new() + x <- pkgnet:::AbstractPackageReporter$new() x$set_package(pkg_name = "baseballstats", pkg_path = "hopefully/not/a/real/path") }, regexp = "Package directory does not exist: hopefully/not/a/real/path") }) test_that("AbstractPackageReporter errors on unimplemented methods", { expect_error({ - x <- AbstractPackageReporter$new() + x <- pkgnet:::AbstractPackageReporter$new() x$get_summary_view() }, regexp = "get_summary_view has not been implemented") expect_error({ - x <- AbstractPackageReporter$new() + x <- pkgnet:::AbstractPackageReporter$new() x$report_markdown_path }, regexp = "this reporter does not have a report markdown path") }) @@ -63,6 +63,5 @@ test_that("AbstractPackageReporter errors on unimplemented methods", { ##### TEST TEAR DOWN ##### -futile.logger::flog.threshold(origLogThreshold) rm(list = ls()) closeAllConnections() From 1c1c13ff89c3d87da45749d481d41fe3507a7c17 Mon Sep 17 00:00:00 2001 From: Jay Qi Date: Mon, 11 Mar 2019 20:46:52 -0500 Subject: [PATCH 3/3] Added block for package_report.Rmd imports --- NAMESPACE | 2 ++ R/CreatePackageReport.R | 3 +++ 2 files changed, 5 insertions(+) diff --git a/NAMESPACE b/NAMESPACE index c8927324..549783a8 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -47,6 +47,8 @@ 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,is) importFrom(rmarkdown,render) diff --git a/R/CreatePackageReport.R b/R/CreatePackageReport.R index 75ec2707..154bb17b 100644 --- a/R/CreatePackageReport.R +++ b/R/CreatePackageReport.R @@ -69,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