Bring back documentation for KorAPConnection params
Change-Id: I8c1ada656d6a0372967911776240862d414eb039
diff --git a/R/KorAPConnection.R b/R/KorAPConnection.R
index 13cc6fe..fe6b9f1 100644
--- a/R/KorAPConnection.R
+++ b/R/KorAPConnection.R
@@ -32,6 +32,60 @@
#' kcon <- KorAPConnection() |> auth()
#' ```
#'
+#' @param KorAPUrl URL of the web user interface of the KorAP server instance you want to access.
+#' Defaults to the environment variable `KORAP_URL` if set and to the IDS Mannheim KorAP main instance
+#' to query DeReKo, otherwise.
+#' @param apiVersion which version of KorAP's API you want to connect to. Defaults to "v1.0".
+#' @param apiUrl URL of the KorAP web service. If not provided, it will be constructed from KorAPUrl and apiVersion.
+#' @param accessToken OAuth2 access token. For queries on corpus parts with restricted
+#' access (e.g. textual queries on IPR protected data), you need to authorize
+#' your application with an access token.
+#' You can obtain an access token in the OAuth settings of your KorAP web interface.
+#'
+#' More details are explained in the
+#' [authorization section](https://github.com/KorAP/RKorAPClient#authorization)
+#' of the RKorAPClient Readme on GitHub.
+#'
+#' To use authorization based on an access token
+#' in subsequent queries, initialize your KorAP connection with:
+#'
+#' ```
+#' kco <- KorAPConnection(accessToken="<access token>")
+#' ```
+#'
+#' In order to make the API
+#' token persistent for the currently used `KorAPUrl` (you can have one
+#' token per KorAPUrl / KorAP server instance), use:
+#'
+#' ```
+#' persistAccessToken(kco)
+#' ```
+#'
+#' This will store it in your keyring using the
+#' [keyring::keyring-package]. Subsequent KorAPConnection() calls will
+#' then automatically retrieve the token from your keying. To stop using a
+#' persisted token, call `clearAccessToken(kco)`. Please note that for
+#' DeReKo, authorized queries will behave differently inside and outside the
+#' IDS, because of the special license situation. This concerns also cached
+#' results which do not take into account from where a request was issued. If
+#' you experience problems or unexpected results, please try `kco <-
+#' KorAPConnection(cache=FALSE)` or use
+#' [clearCache()] to clear the cache completely.
+#'
+#' An alternative to using an access token is to use a browser-based oauth2 workflow
+#' to obtain an access token. This can be done with the [auth()] method.
+#' @param oauthClient OAuth2 client object (advanced users only).
+#' @param oauthScope OAuth2 scope. Defaults to "search match_info".
+#' @param authorizationSupported logical that indicates if authorization is supported/necessary for the current KorAP instance. Automatically set during initialization.
+#' @param userAgent user agent string. Defaults to "R-KorAP-Client".
+#' @param timeout timeout in seconds for API requests (this does not influence server internal timeouts). Defaults to 240 seconds.
+#' @param verbose logical that decides whether following operations will default to
+#' be verbose. Defaults to FALSE.
+#' @param cache logical that decides if API calls are cached locally. You can clear
+#' the cache with [clearCache()]. Defaults to TRUE.
+#'
+#' @return [KorAPConnection()] object that can be used e.g. with [corpusQuery()]
+#'
#' @details
#' The KorAPConnection object contains various configuration slots for advanced users:
#' KorAPUrl (server URL), apiVersion, accessToken (OAuth2 token),
@@ -58,7 +112,9 @@
#' @param .Object KorAPConnection object
#' @param KorAPUrl URL of the web user interface of the KorAP server instance you want to access.
#' Defaults to the environment variable `KORAP_URL` if set and to the IDS Mannheim KorAP main instance
-#' to query DeReKo, otherwise.
+#' (<https://korap.ids-mannheim.de/>) to query DeReKo, otherwise.
+#' In order to access the KorAP instance at the DNB to query the contemporary fiction corpus DeLiKo@@DNB,
+#' for example, set `KorAPUrl` to `https://korap.dnb.de/`.
#' @param apiVersion which version of KorAP's API you want to connect to.
#' @param apiUrl URL of the KorAP web service.
#' @param accessToken OAuth2 access token. For queries on corpus parts with restricted
@@ -527,7 +583,7 @@
#' kco <- KorAPConnection()
#' clearCache(kco)
#' }
-#'
+#'
#' @aliases clearCache
#' @export
setMethod("clearCache", "KorAPConnection", function(kco) {