Apply changes to docs after review.

r-world-devs · Oct 2, 2023 · beafef6 · beafef6
1 parent a777947
commit beafef6
Show file tree

Hide file tree

Showing 17 changed files with 87 additions and 84 deletions.
diff --git a/NAMESPACE b/NAMESPACE
@@ -28,7 +28,6 @@ importFrom(cli,cli_alert_success)
 importFrom(cli,cli_alert_warning)
 importFrom(cli,col_green)
 importFrom(cli,col_yellow)
-importFrom(data.table,":=")
 importFrom(data.table,as.data.table)
 importFrom(data.table,rbindlist)
 importFrom(data.table,setorder)

diff --git a/R/GitHost.R b/R/GitHost.R
@@ -9,12 +9,12 @@
 GitHost <- R6::R6Class("GitHost",
   public = list(
 
-    #' @description Create a new `GitHost` object
+    #' @description Create a new `GitHost` object.
     #' @param orgs A character vector of organisations (owners of repositories
     #'   in case of GitHub and groups of projects in case of GitLab).
     #' @param token A token.
-    #' @param api_url An API url.
-    #' @return A new `GitHost` object
+    #' @param api_url An API URL.
+    #' @return A new `GitHost` object.
     initialize = function(orgs = NA,
                           token = NA,
                           api_url = NA) {
@@ -98,7 +98,7 @@ GitHost <- R6::R6Class("GitHost",
     #' @param date_from A starting date to look commits for.
     #' @param date_until An end date to look commits for.
     #' @param settings A list of `GitStats` settings.
-    #' @return A data.frame of commits
+    #' @return A data.frame of commits.
     pull_commits = function(date_from,
                             date_until = Sys.Date(),
                             settings) {
@@ -150,9 +150,9 @@ GitHost <- R6::R6Class("GitHost",
       return(commits_table)
     },
 
-    #' @description Get information about users
-    #' @param users A character vector of users
-    #' @return Table of users
+    #' @description Pull information about users.
+    #' @param users A character vector of users.
+    #' @return Table of users.
     pull_users = function(users) {
       users_table <- purrr::map(private$engines, function(engine) {
         if (inherits(engine, "EngineGraphQL")) {
@@ -167,7 +167,7 @@ GitHost <- R6::R6Class("GitHost",
   ),
   private = list(
 
-    # @field A REST API url.
+    # @field A REST API URL.
     api_url = NULL,
 
     # @field A token.
@@ -346,7 +346,7 @@ GitHost <- R6::R6Class("GitHost",
         purrr::list_rbind()
     },
 
-    # add do repos table `api_url` column
+    # @description Add `api_url` column to repos table.
     add_repo_api_url = function(repos_table){
       if (length(repos_table) > 0) {
         repos_table <- if (private$host == "GitHub") {

diff --git a/R/GitStats.R b/R/GitStats.R
@@ -1,7 +1,7 @@
 #' @noRd
 #' @importFrom R6 R6Class
 #' @importFrom cli cli_alert_info cli_alert_success cli_alert_warning col_yellow
-#' @importFrom data.table rbindlist :=
+#' @importFrom data.table rbindlist
 #' @importFrom dplyr glimpse
 #' @importFrom magrittr %>%
 #' @importFrom purrr map map_chr
@@ -73,12 +73,12 @@ GitStats <- R6::R6Class("GitStats",
       private$settings$print_out <- print_out
     },
 
-    #' @description Method to set connections to Git platforms
+    #' @description Method to set connections to Git platforms.
     #' @param api_url A character, url address of API.
     #' @param token A token.
     #' @param orgs A character vector of organisations (owners of repositories
     #'   in case of GitHub and groups of projects in case of GitLab).
-    #' @return Nothing, puts connection information into `$hosts` slot
+    #' @return Nothing, puts connection information into `$hosts` slot.
     set_host = function(api_url,
                         token,
                         orgs) {
@@ -105,7 +105,7 @@ GitStats <- R6::R6Class("GitStats",
     #' @description A method to add a team member.
     #' @param member_name Name of a member.
     #' @param ... User names on Git platforms.
-    #' @return Nothing, pass information on team member to `GitStats`.
+    #' @return Nothing, passes information on team member to `GitStats`.
     set_team_member = function(member_name,
                                ...) {
       team_member <- list(
@@ -120,7 +120,7 @@ GitStats <- R6::R6Class("GitStats",
     #'   a team or by a keyword.
     #' @param add_contributors A boolean to decide whether to add contributors
     #'   information to repositories.
-    #' @return A data.frame of repositories
+    #' @return A data.frame of repositories.
     pull_repos = function(add_contributors = FALSE) {
       if (private$settings$search_param == "team") {
         if (length(private$settings$team) == 0) {
@@ -160,9 +160,9 @@ GitStats <- R6::R6Class("GitStats",
     },
 
     #' @description A method to get information on commits.
-    #' @param date_from A starting date to look commits for
-    #' @param date_until An end date to look commits for
-    #' @return A data.frame of commits
+    #' @param date_from A starting date for commits.
+    #' @param date_until An end date for commits.
+    #' @return A data.frame of commits.
     pull_commits = function(date_from,
                            date_until) {
       if (is.null(date_from)) {
@@ -214,30 +214,30 @@ GitStats <- R6::R6Class("GitStats",
       return(invisible(self))
     },
 
-    #' @description Print organizations.
+    #' @description Return organizations vector from GitStats.
     get_orgs = function() {
       purrr::map(private$hosts, function(host) {
         orgs <- host$.__enclos_env__$private$orgs
         purrr::map_vec(orgs, ~ gsub("%2f", "/", .))
         }) %>% unlist()
     },
 
-    #' @description Print repositories output.
+    #' @description Return repositories table from GitStats.
     get_repos = function() {
       private$repos
     },
 
-    #' @description Print commits output.
+    #' @description Return commits table from GitStats.
     get_commits = function() {
       private$commits
     },
 
-    #' @description Print users output.
+    #' @description Return users table from GitStats.
     get_users = function() {
       private$users
     },
 
-    #' @description A print method for a GitStats object
+    #' @description A print method for a GitStats object.
     print = function() {
       cat(paste0("A <GitStats> object for ", length(private$hosts), " hosts:"), sep = "\n")
       hosts <- purrr::map_chr(private$hosts, function(host) {
@@ -283,8 +283,8 @@ GitStats <- R6::R6Class("GitStats",
     users = NULL,
 
     # @description Check whether the urls do not repeat in input.
-    # @param host An object of GitPlatform class
-    # @return A GitPlatform object
+    # @param host An object of GitPlatform class.
+    # @return A GitPlatform object.
     check_for_duplicate_hosts = function(host) {
       if (length(private$hosts) > 0) {
         hosts_to_check <- append(host, private$hosts)
@@ -304,19 +304,19 @@ GitStats <- R6::R6Class("GitStats",
       host
     },
 
-    # @description Helper to check if there are any hosts
+    # @description Helper to check if there are any hosts.
     check_for_host = function() {
       if (length(private$hosts) == 0) {
         cli::cli_abort("Add first your hosts with `set_host()`.")
       }
     },
 
-    # @description Switcher to manage language names
+    # @description Switcher to manage language names.
     # @details E.g. GitLab API will not filter
     #   properly if you provide 'python' language
     #   with small letter.
-    # @param language A character, language name
-    # @return A character
+    # @param language Code programming language.
+    # @return A character.
     language_handler = function(language) {
       if (language != "All") {
         substr(language, 1, 1) <- toupper(substr(language, 1, 1))

diff --git a/R/get_stats.R b/R/get_stats.R
@@ -76,7 +76,7 @@ get_commits_stats <- function(gitstats_obj,
 }
 
 #' @noRd
-#' @description A constructor for `commits_stats` class
+#' @description A constructor for `commits_stats` class.
 commits_stats <- function(object, time_interval) {
   stopifnot(inherits(object, "grouped_df"))
   object <- dplyr::ungroup(object)

diff --git a/R/gitstats_functions.R b/R/gitstats_functions.R
@@ -11,16 +11,15 @@ create_gitstats <- function() {
 #' @title Set Git host
 #' @name set_host
 #' @param gitstats_obj A GitStats object.
-#' @param api_url A character, url address of API.
+#' @param api_url A character, URL address of API.
 #' @param token A token.
 #' @param orgs A character vector of organisations (owners of repositories in
 #'   case of GitHub and groups of projects in case of GitLab). You do not need
 #'   to define `orgs` if you wish to scan whole internal Git platform (such as
 #'   enterprise version of GitHub or GitLab). In case of a public one (like
 #'   GitHub) you need to define `orgs` as scanning through all organizations
-#'   would be an overkill.
-#' @return A `GitStats` class object with added information on connection
-#'   (`$hosts` field).
+#'   may take large amount of time.
+#' @return A `GitStats` object with added information on host.
 #' @examples
 #' \dontrun{
 #' my_gitstats <- create_gitstats() %>%
@@ -54,8 +53,8 @@ set_host <- function(gitstats_obj,
 #' @param search_param One of three: team, orgs or phrase.
 #' @param team_name Name of a team.
 #' @param phrase A phrase to look for.
-#' @param language A language of programming code.
-#' @param print_out A boolean to decide whether to print output
+#' @param language Code programming language.
+#' @param print_out A boolean to decide whether to print output.
 #' @return A `GitStats` object.
 #' @examples
 #' \dontrun{
@@ -68,11 +67,11 @@ set_host <- function(gitstats_obj,
 #' }
 #' @export
 set_params <- function(gitstats_obj,
-                  search_param = NULL,
-                  team_name = NULL,
-                  phrase = NULL,
-                  language = "All",
-                  print_out = TRUE) {
+                       search_param = NULL,
+                       team_name = NULL,
+                       phrase = NULL,
+                       language = "All",
+                       print_out = TRUE) {
   gitstats_obj$set_params(
     search_param = search_param,
     team_name = team_name,
@@ -87,7 +86,7 @@ set_params <- function(gitstats_obj,
 #' @title Set your team member
 #' @name set_team_member
 #' @description Passes information on team member to your `team` field.
-#' @param gitstats_obj `GitStats` object.
+#' @param gitstats_obj A GitStats object.
 #' @param member_name Name of a member.
 #' @param ... All user logins.
 #' @return `GitStats` object with new information on team member.
@@ -128,7 +127,7 @@ set_team_member <- function(gitstats_obj,
 #'   `pull_repos_contributors()` on the `GitStats` object with the `repositories`
 #'   output. \cr\cr When pulling repositories by \bold{`team`} the parameter
 #'   always turns to `TRUE` and pulls information on `contributors`.
-#' @return A `GitStats` class object with updated `$repos` field.
+#' @return A `GitStats` class object with repositories table.
 #' @examples
 #' \dontrun{
 #' my_gitstats <- create_gitstats() %>%
@@ -153,9 +152,10 @@ pull_repos <- function(gitstats_obj, add_contributors = FALSE) {
 #' @title Pull information on contributors
 #' @name pull_repos_contributors
 #' @param gitstats_obj A GitStats object.
-#' @description A method to add information on contributors to already pulled
-#'   repositories table.
-#' @return A table of repositories with added information on contributors.
+#' @description Adds information on contributors to already pulled repositories
+#'   table.
+#' @return  A `GitStats` class object with repositories table with added
+#'   information on contributors.
 #' @export
 pull_repos_contributors <- function(gitstats_obj) {
   gitstats_obj$pull_repos_contributors()
@@ -164,11 +164,12 @@ pull_repos_contributors <- function(gitstats_obj) {
 
 #' @title Pull information on commits
 #' @name pull_commits
-#' @description List all commits from all repositories for an organization or a team.
+#' @description List all commits from all repositories for an organization or a
+#'   team.
 #' @param gitstats_obj  A GitStats object.
-#' @param date_from A starting date to look commits for
-#' @param date_until An end date to look commits for
-#' @return A `GitStats` class object with updated `$commits` field.
+#' @param date_from A starting date of commits.
+#' @param date_until An end date of commits.
+#' @return A `GitStats` class object with commits table.
 #' @examples
 #' \dontrun{
 #' my_gitstats <- create_gitstats() %>%
@@ -191,8 +192,8 @@ pull_repos_contributors <- function(gitstats_obj) {
 #' }
 #' @export
 pull_commits <- function(gitstats_obj,
-                        date_from = NULL,
-                        date_until = Sys.time()) {
+                         date_from = NULL,
+                         date_until = Sys.time()) {
   gitstats_obj$pull_commits(
     date_from = date_from,
     date_until = date_until
@@ -221,10 +222,10 @@ pull_commits <- function(gitstats_obj,
 #'   ) %>%
 #'   pull_users(c("maciekabanas", "marcinkowskak"))
 #' }
-#' @return A table of users.
+#' @return A `GitStats` object with table of users.
 #' @export
 pull_users <- function(gitstats_obj,
-                      users){
+                       users){
   gitstats_obj$pull_users(
     users = users
   )
@@ -236,7 +237,7 @@ pull_users <- function(gitstats_obj,
 #' @description Sets all settings to default: search_param to `org`, language to
 #'   `All` and other to `NULL`s.
 #' @param gitstats_obj A GitStats object.
-#' @return A GitStats object.
+#' @return A `GitStats` object.
 #' @export
 reset <- function(gitstats_obj){
   priv <- environment(gitstats_obj$set_params)$private
@@ -254,9 +255,10 @@ reset <- function(gitstats_obj){
 
 #' @title Reset language settings
 #' @name reset_language
-#' @description Sets language parameter to NULL (switches of filtering by language.)
+#' @description Sets language parameter to \code{NULL} (switches of filtering by
+#'   language.).
 #' @param gitstats_obj A GitStats object.
-#' @return A GitStats object.
+#' @return A `GitStats` object.
 #' @export
 reset_language <- function(gitstats_obj){
   priv <- environment(gitstats_obj$set_params)$private
@@ -267,9 +269,9 @@ reset_language <- function(gitstats_obj){
 
 #' @title Get organizations
 #' @name get_orgs
-#' @description Retrieves organizations downloaded in `GitStats`. Especially
-#'   helpful when user is scanning whole git platform and want to have a glimpse
-#'   at organizations.
+#' @description Retrieves organizations set or pulled by `GitStats`. Especially
+#'   helpful when user is scanning whole git platform and wants to have a
+#'   glimpse at organizations.
 #' @param gitstats_obj A GitStats object.
 #' @return A vector of organizations.
 #' @export

diff --git a/R/plots.R b/R/plots.R
@@ -5,7 +5,7 @@
 #' @importFrom stringr str_remove_all
 #' @importFrom data.table setorder as.data.table
 
-#' @title Plot Git Statistics.
+#' @title Plot Git statistics
 #' @name gitstats_plot
 #' @description A generic to plot statistics from repositories or commits.
 #' @param stats_table A table with repository or commits statistics.

diff --git a/man/get_orgs.Rd b/man/get_orgs.Rd
diff --git a/man/gitstats_plot.Rd b/man/gitstats_plot.Rd