From a47c322658afb7de2d943e72278c76890160891f Mon Sep 17 00:00:00 2001 From: Mark Burgess Date: Mon, 9 Dec 2024 10:32:08 -1000 Subject: [PATCH] i #323 Updated function documentation. - Updated notebook to include section on where to place created tokens to use endpoints. - Updated pr_comments function documentation --- R/github.R | 24 ++++++++++++++++++++++-- vignettes/download_github_comments.Rmd | 2 ++ 2 files changed, 24 insertions(+), 2 deletions(-) diff --git a/R/github.R b/R/github.R index 266f006..91875b3 100644 --- a/R/github.R +++ b/R/github.R @@ -739,6 +739,7 @@ github_parse_project_pull_request <- function(api_responses){ #' @param repo GitHub's repository name (e.g. kaiaulu) #' @param token Your GitHub API token #' @param since Optional parameter to specify pulling only comments updated after this date +#' @references For details, see \url{https://docs.github.com/en/rest/pulls/comments?apiVersion=2022-11-28#about-pull-request-review-comments} #' @export github_api_project_pr_comments <- function(owner, repo, token, since=NULL) { if (!is.null(since)) { @@ -765,7 +766,26 @@ github_api_project_pr_comments <- function(owner, repo, token, since=NULL) { #' Note not all columns available in the downloaded json are parsed. #' Note this is different from the `github_parse_project_issue_or_pr_comments` function. #' This function only parses for the in-line code and comments made on the pull request. -#' +#' `file_path` A string containing the filepath of the file the review comment is made on. +#' `start_line` An integer value of the first line number if multiple lines are selected when +#' making the comment, or null if only 1 line is selected. Will also return null if line is deleted +#' in later commits. +#' `line` An integer value of the last line number if multiple lines are selected when +#' making the comment, or the the line number when only 1 line is selected. Will return +#' 1 if no lines are selected when making the comment or null if the line is deleted +#' in later commits. +#' `original_start_line` An integer value of the first line number if multiple lines are selected when +#' making the comment, or null if only 1 line is selected. The line number integer will match the line +#' number at the time the review comment is made, regardless if a later commit changes the line number. +#' `original_line` An integer value of the last line number if multiple lines are selected when +#' making the comment, or the the line number when only 1 line is selected. Will return +#' 1 if no lines are selected when making the comment. The line number integer will match the line +#' number at the time the review comment is made, regardless if a later commit changes the line number. +#' `diff_hunk` A string containing the code hunk the review comment is referencing. +#' It will contain the lines from the start of the (+/-) hunk until the line +#' associated by the review comment. Will return null if the review comment is not +#' tied to a specific line. +#' `body` A string containing main text of the review comment. #' @param api_responses API response obtained from github_api_* function. #' @export github_parse_project_pr_comments <- function(api_responses) { @@ -816,7 +836,7 @@ github_parse_project_pr_comments <- function(api_responses) { #' @param verbose boolean value. When set to true, it prints operational messages including #' greatest dates and the file name that contains the greatest date. #' @export -#' @references For details, see \url{https://docs.github.com/en/rest/reference/issues#list-repository-issues}. +#' @references For details, see For details, see \url{https://docs.github.com/en/rest/pulls/comments?apiVersion=2022-11-28#about-pull-request-review-comments}. #' @seealso \code{link{github_api_project_pr_comments}} to download all pull request comment data #' @seealso \code{link{format_created_at_from_file}} for function that iterates through #' a .json file and returns the greatest 'created_at' value diff --git a/vignettes/download_github_comments.Rmd b/vignettes/download_github_comments.Rmd index 1b3a4ea..f6a8c7a 100644 --- a/vignettes/download_github_comments.Rmd +++ b/vignettes/download_github_comments.Rmd @@ -22,6 +22,8 @@ GitHub limits the number of API calls per IP to only 60 attempts **every hour** If using a personal account token from a free GitHub account, the number of API calls per hour increases to 5000 **per hour**. Therefore, it is recommended you create a personal token by following the [GitHub Documentation instructions](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token#:~:text=Creating%20a%20token.%201%20Verify%20your%20email%20address%2C,able%20to%20see%20the%20token%20again.%20More%20items). The process should not take more than 2 minutes. +The token should then be copied and pasted into `../.ssh/github_token`. Both the `.ssh` folder and `github_token` file may need to be created manually. Check for hidden folders before creating the `.ssh` folder. The `github_token` file should not have any file extensions. + ## Libraries To use the notebook, you will need to ensure you have the required R packages installed.