diff --git a/R/KorAPConnection.R b/R/KorAPConnection.R
index 8921e44..ea6d5c4 100644
--- a/R/KorAPConnection.R
+++ b/R/KorAPConnection.R
@@ -30,13 +30,29 @@
 #' @param KorAPUrl URL of the web user interface of the KorAP server instance you want to access.
 #' @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. To use authorization based on an access token
-#'   in subsequent queries, initialize your KorAP connection with
-#'   `kco <- new("KorAPConnection", accessToken="<access token>")`.
+#' @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.
+#'   How to obtain an access token for the DeReKo KorAP instance is 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 <- new("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
+#'   token per KorAPUrl / KorAP server instance), use:
+#'
+#'   ```
+#'   persistAccessToken(kco)
+#'   ```
+#'
+#'   This will store it in your keyring using the
 #'   [keyring()] package. Subsequent new("KorAPConnection") calls will
 #'   then automatically retrieve the token from your keying. To stop using a
 #'   persisted token, call `clearAccessToken(kco)`. Please note that for
@@ -46,6 +62,7 @@
 #'   you experience problems or unexpected results, please try `kco <-
 #'   new("KorAPConnection", cache=FALSE)` or use
 #'   [clearCache()] to clear the cache completely.
+#'
 #' @param userAgent user agent string.
 #' @param timeout tineout in seconds for API requests (this does not influence server internal timeouts).
 #' @param verbose logical that decides whether following operations will default to
diff --git a/R/KorAPQuery.R b/R/KorAPQuery.R
index eb2afbd..9114c83 100644
--- a/R/KorAPQuery.R
+++ b/R/KorAPQuery.R
@@ -87,7 +87,12 @@
 #' @param query string that contains the corpus query. The query language depends on the `ql` parameter. Either `query` must be provided or `KorAPUrl`.
 #' @param vc string describing the virtual corpus in which the query should be performed. An empty string (default) means the whole corpus, as far as it is license-wise accessible.
 #' @param KorAPUrl instead of providing the query and vc string parameters, you can also simply copy a KorAP query URL from your browser and use it here (and in `KorAPConnection`) to provide all necessary information for the query.
-#' @param metadataOnly logical that determines whether queries should return only metadata without any snippets. This can also be useful to prevent access rewrites. Note that the default value is TRUE, unless the connection is authorized (currently not possible).
+#' @param metadataOnly logical that determines whether queries should return only metadata without any snippets. This can also be useful to prevent access rewrites. Note that the default value is TRUE.
+#'    If you want your corpus queries to return not only metadata, but also KWICS, you need to authorize
+#'    your RKorAPClient application as explained in the
+#'   [authorization section](https://github.com/KorAP/RKorAPClient#authorization)
+#'   of the RKorAPClient Readme on GitHub and set the `metadataOnly` parameter to
+#'   `FALSE`.
 #' @param ql string to choose the query language (see [section on Query Parameters](https://github.com/KorAP/Kustvakt/wiki/Service:-Search-GET#user-content-parameters) in the Kustvakt-Wiki for possible values.
 #' @param fields (meta)data fields that will be fetched for every match.
 #' @param accessRewriteFatal abort if query or given vc had to be rewritten due to insufficient rights (not yet implemented).