[R] Update R6 object documentation (#19679)

* Remove @export and titles from R6 methods * Remove redundant methods docs from R api.mustache * Build project
OpenAPITools · Sep 26, 2024 · 29c3b02 · 29c3b02
1 parent a6581e8
commit 29c3b02
Show file tree

Hide file tree

Showing 125 changed files with 1,450 additions and 6,122 deletions.
diff --git a/modules/openapi-generator/src/main/resources/r/ApiResponse.mustache b/modules/openapi-generator/src/main/resources/r/ApiResponse.mustache
@@ -17,8 +17,7 @@ ApiResponse <- R6::R6Class(
     status_code = NULL,
     status_code_desc = NULL,
     headers = NULL,
-    #' Initialize a new ApiResponse class.
-    #'
+
     #' @description
     #' Initialize a new ApiResponse class.
     #'
@@ -27,7 +26,6 @@ ApiResponse <- R6::R6Class(
     #' @param status_code The HTTP response status code.
     #' @param status_code_desc The brief description of the HTTP response status code.
     #' @param headers The HTTP response headers.
-    #' @export
     initialize = function(content = NULL,
                           response = NULL,
                           status_code = NULL,
@@ -40,15 +38,13 @@ ApiResponse <- R6::R6Class(
       self$headers <- headers
     },
 
-    #' Return the response as text
-    #'
+
     #' @description
     #' The response is stored as a raw vector. Use this to access the response after
     #' converting it to text. If the response is not coercible to text NA is returned.
     #'
     #' @param from_encoding The encoding of the raw response.
     #' @param to_encoding The target encoding of the return value.
-    #' @export
     response_as_text = function(from_encoding = "", to_encoding = "UTF-8") {
       if (is.null(self$response)) {
         self$response <- charToRaw(jsonlite::toJSON("NULL"))

diff --git a/modules/openapi-generator/src/main/resources/r/api.mustache b/modules/openapi-generator/src/main/resources/r/api.mustache
@@ -6,79 +6,6 @@
 #' @format An \code{R6Class} generator object
 #' @field api_client Handles the client-server communication.
 #'
-#' @section Methods:
-{{! Adding the below changes for generating documentation for the api methods. }}
-#' \describe{
-{{#operation}}
-#' \strong{ {{operationId}} } \emph{ {{#lambdaRdocEscape}}{{summary}}{{/lambdaRdocEscape}} }
-{{#notes}}
-#' {{#lambdaRdocEscape}}{{{.}}}{{/lambdaRdocEscape}}
-{{/notes}}
-#'
-#' \itemize{
-{{#allParams}}
-{{#isEnum}}
-#' \item \emph{ @param } {{paramName}} Enum < {{#allowableValues}}{{values}}{{/allowableValues}} >
-{{/isEnum}}
-{{^isEnum}}
-{{#isContainer}}
-{{#isArray}}
-{{#items}}
-{{#isPrimitiveType}}
-#' \item \emph{ @param } {{paramName}} list( {{dataType}} )
-{{/isPrimitiveType}}
-{{^isPrimitiveType}}
-#' \item \emph{ @param } {{paramName}} list( \link{{=<% %>=}}{<%dataType%>}<%={{ }}=%> )
-{{/isPrimitiveType}}
-{{/items}}
-{{/isArray}}
-{{#isMap}}
-{{#isPrimitiveType}}
-#' \item \emph{ @param } {{paramName}} named list( {{dataType}} )
-{{/isPrimitiveType}}
-{{^isPrimitiveType}}
-#' \item \emph{ @param } {{paramName}} named list( \link{{=<% %>=}}{<%dataType%>}<%={{ }}=%> )
-{{/isPrimitiveType}}
-{{/isMap}}
-{{/isContainer}}
-{{^isContainer}}
-{{#isPrimitiveType}}
-#' \item \emph{ @param } {{paramName}} {{dataType}}
-{{/isPrimitiveType}}
-{{^isPrimitiveType}}
-#' \item \emph{ @param } {{paramName}} \link{{=<% %>=}}{<%dataType%>}<%={{ }}=%>
-{{/isPrimitiveType}}
-{{/isContainer}}
-{{/isEnum}}
-{{/allParams}}
-{{#returnType}}
-{{^returnTypeIsPrimitive}}
-#' \item \emph{ @returnType } {{#returnContainer}}{{#isArray}}list( {{/isArray}}{{#isMap}}named list( {{/isMap}}{{/returnContainer}}\link{{=<% %>=}}{<%#returnContainer%><%={{ }}=%>{{returnBaseType}}{{/returnContainer}}{{^returnContainer}}{{returnType}}{{=<% %>=}}<%/returnContainer%>}<%={{ }}=%>{{#returnContainer}}{{#isArray}} ){{/isArray}}{{#isMap}} ){{/isMap}}{{/returnContainer}} \cr
-{{/returnTypeIsPrimitive}}
-{{/returnType}}
-#'
-{{#useRlangExceptionHandling}}
-#' \item On encountering errors, an error of subclass ApiException will be thrown.
-{{/useRlangExceptionHandling}}
-#'
-{{#responses}}
-#' \item status code : {{code}} | {{{message}}}
-#'
-#'{{#dataType}} \item return type : {{{.}}}{{/dataType}}
-#' \item response headers :
-#'
-#' \tabular{ll}{
-{{#headers}}
-#' {{name}} \tab {{{description}}} \cr
-{{/headers}}
-#' }
-{{/responses}}
-#' }
-#'
-{{/operation}}
-#' }
-#'
-#'
 #' @examples
 #' \dontrun{
 {{#operation}}
@@ -185,13 +112,11 @@
   "{{classname}}",
   public = list(
     api_client = NULL,
-    #' Initialize a new {{{classname}}}.
-    #'
+
     #' @description
     #' Initialize a new {{{classname}}}.
     #'
     #' @param api_client An instance of API client.
-    #' @export
     initialize = function(api_client) {
       if (!missing(api_client)) {
         self$api_client <- api_client
@@ -200,8 +125,7 @@
       }
     },
     {{#operation}}
-    #' {{{summary}}}
-    #'
+
     #' @description
     #' {{{description}}}{{^description}}{{{summary}}}{{/description}}
     #'
@@ -218,8 +142,8 @@
     #' @param data_file (optional) name of the data file to save the result
     {{/returnType}}
     #' @param ... Other optional arguments
+    #'
     #' @return {{{returnType}}}{{^returnType}}void{{/returnType}}
-    #' @export
     {{{operationId}}} = function({{#requiredParams}}{{paramName}}, {{/requiredParams}}{{#optionalParams}}{{paramName}} = {{^defaultValue}}NULL{{/defaultValue}}{{{defaultValue}}}, {{/optionalParams}}{{#vendorExtensions.x-streaming}}stream_callback = NULL, {{/vendorExtensions.x-streaming}}{{#returnType}}data_file = NULL, {{/returnType}}...) {
       local_var_response <- self${{{operationId}}}{{WithHttpInfo}}({{#allParams}}{{paramName}}, {{/allParams}}{{#vendorExtensions.x-streaming}}stream_callback = stream_callback, {{/vendorExtensions.x-streaming}}{{#returnType}}data_file = data_file, {{/returnType}}...)
       {{#vendorExtensions.x-streaming}}
@@ -238,8 +162,7 @@
         local_var_response
       }
     },
-    #' {{{summary}}}
-    #'
+
     #' @description
     #' {{{description}}}{{^description}}{{{summary}}}{{/description}}
     #'
@@ -256,8 +179,8 @@
     #' @param data_file (optional) name of the data file to save the result
     {{/returnType}}
     #' @param ... Other optional arguments
+    #'
     #' @return API response ({{{returnType}}}{{^returnType}}void{{/returnType}}) with additional information such as HTTP status code, headers
-    #' @export
     {{{operationId}}}{{WithHttpInfo}} = function({{#requiredParams}}{{paramName}}, {{/requiredParams}}{{#optionalParams}}{{paramName}} = {{^defaultValue}}NULL{{/defaultValue}}{{{defaultValue}}}, {{/optionalParams}}{{#vendorExtensions.x-streaming}}stream_callback = NULL, {{/vendorExtensions.x-streaming}}{{#returnType}}data_file = NULL, {{/returnType}}...) {
       args <- list(...)
       query_params <- list()

diff --git a/modules/openapi-generator/src/main/resources/r/api_client.mustache b/modules/openapi-generator/src/main/resources/r/api_client.mustache
@@ -158,8 +158,7 @@ ApiClient <- R6::R6Class(
         self$max_retry_attempts <- max_retry_attempts
       }
     },
-    #' Prepare to make an API call with the retry logic.
-    #'
+
     #' @description
     #' Prepare to make an API call with the retry logic.
     #'
@@ -174,8 +173,8 @@ ApiClient <- R6::R6Class(
     #' @param body The HTTP request body.
     #' @param stream_callback Callback function to process the data stream
     #' @param ... Other optional arguments.
+    #'
     #' @return HTTP response
-    #' @export
     CallApi = function(url, method, query_params, header_params, form_params,
                        file_params, accepts, content_types,
                        body, stream_callback = NULL, ...) {
@@ -205,8 +204,7 @@ ApiClient <- R6::R6Class(
 
       resp
     },
-    #' Make an API call
-    #'
+
     #' @description
     #' Make an API call
     #'
@@ -221,8 +219,8 @@ ApiClient <- R6::R6Class(
     #' @param body The HTTP request body.
     #' @param stream_callback Callback function to process data stream
     #' @param ... Other optional arguments.
+    #'
     #' @return HTTP response
-    #' @export
     Execute = function(url, method, query_params, header_params,
                        form_params, file_params,
                        accepts, content_types,
@@ -316,40 +314,39 @@ ApiClient <- R6::R6Class(
 
         # return ApiResponse
         api_response <- ApiResponse$new()
-        api_response$status_code <- httr::status_code(httr_response) 
+        api_response$status_code <- httr::status_code(httr_response)
         api_response$status_code_desc <- httr::http_status(httr_response)$reason
         api_response$response <- httr::content(httr_response, "raw")
         api_response$headers <- httr::headers(httr_response)
 
         api_response
       }
     },
-    #' Deserialize the content of API response to the given type.
-    #'
+
     #' @description
     #' Deserialize the content of API response to the given type.
     #'
     #' @param raw_response Raw response.
     #' @param return_type R return type.
     #' @param pkg_env Package environment.
+    #'
     #' @return Deserialized object.
-    #' @export
     deserialize = function(raw_response, return_type, pkg_env) {
       resp_obj <- jsonlite::fromJSON(raw_response)
       self$deserializeObj(resp_obj, return_type, pkg_env)
     },
-    #' Deserialize the response from jsonlite object based on the given type
-    #'
+
     #' @description
     #' Deserialize the response from jsonlite object based on the given type
     #' by handling complex and nested types by iterating recursively
-    #' Example return_types will be like "array[integer]", "map(Pet)", "array[map(Tag)]", etc.,
+    #' Example return_types will be like "array[integer]", "map(Pet)",
+    #' "array[map(Tag)]", etc.,
     #'
     #' @param obj Response object.
     #' @param return_type R return type.
     #' @param pkg_env Package environment.
+    #'
     #' @return Deserialized object.
-    #' @export
     deserializeObj = function(obj, return_type, pkg_env) {
       return_obj <- NULL
       primitive_types <- c("character", "numeric", "integer", "logical", "complex")
@@ -411,15 +408,14 @@ ApiClient <- R6::R6Class(
       }
       return_obj
     },
-    #' Return a property header (for accept or content-type).
-    #'
+
     #' @description
     #' Return a property header (for accept or content-type). If JSON-related MIME is found,
     #' return it. Otherwise, return the first one, if any.
     #'
     #' @param headers A list of headers
+    #'
     #' @return A header (e.g. 'application/json')
-    #' @export
     select_header = function(headers) {
       if (length(headers) == 0) {
         return(invisible(NULL))

diff --git a/modules/openapi-generator/src/main/resources/r/api_exception.mustache b/modules/openapi-generator/src/main/resources/r/api_exception.mustache
@@ -22,15 +22,13 @@ ApiException <- R6::R6Class(
     {{#errorObjectType}}
     error_object = NULL,
     {{/errorObjectType}}
-    #' Initialize a new ApiException class.
-    #'
+
     #' @description
-    #' Initialize a new ApiExceptino class.
+    #' Initialize a new ApiException class.
     #'
     #' @param status HTTP status.
     #' @param reason Reason of the ApiException.
     #' @param http_response HTTP response object.
-    #' @export
     initialize = function(status = NULL, reason = NULL, http_response = NULL) {
       if (!is.null(http_response)) {
         self$status <- http_response$status_code
@@ -54,13 +52,11 @@ ApiException <- R6::R6Class(
         {{/errorObjectType}}
       }
     },
-    #' Returns the string format of ApiException.
-    #'
+
     #' @description
     #' Returns the string format of ApiException.
     #'
     #' @return the string format of ApiException.
-    #' @export
     toString = function() {
       errorMsg <- ""
       errorMsg <- paste("status : ", self$status, "\n", sep = "")