diff --git a/R/KorAPConnection.R b/R/KorAPConnection.R
index 1d567a8..f1f433d 100644
--- a/R/KorAPConnection.R
+++ b/R/KorAPConnection.R
@@ -5,28 +5,44 @@
 setClassUnion("listOrNULL", c("list", "NULL"))
 # setOldClass("httr2_oauth_client")
 
-#' Class KorAPConnection
+#' Connect to KorAP Server
 #'
-#' `KorAPConnection` objects represent the connection to a KorAP server.
-#' New `KorAPConnection` objects can be created by `KorAPConnection()`.
+#' `KorAPConnection()` creates a connection to a KorAP server for corpus queries.
+#' This is your starting point for all corpus analysis tasks.
 #'
+#' Use `KorAPConnection()` to connect, then `corpusQuery()` to search, and
+#' `fetchAll()` to retrieve results. For authorized access to restricted corpora,
+#' use `auth()` or provide an `accessToken`.
+#'
+#' @section Basic Workflow:
+#' ```r
+#' # Connect to KorAP
+#' kcon <- KorAPConnection()
+#'
+#' # Search for a term
+#' query <- corpusQuery(kcon, "Ameisenplage")
+#'
+#' # Get all results
+#' results <- fetchAll(query)
+#' ```
+#'
+#' @section Authorization:
+#' For access to restricted corpora, authorize your connection:
+#' ```r
+#' kcon <- KorAPConnection() |> auth()
+#' ```
+#'
+#' @details
+#' The KorAPConnection object contains various configuration slots for advanced users:
+#' KorAPUrl (server URL), apiVersion, accessToken (OAuth2 token),
+#' timeout (request timeout), verbose (logging), cache (local caching),
+#' and other technical parameters. Most users can ignore these implementation details.
+#'
+#' @family initialization functions
 #' @import R.cache
 #' @import utils
 #' @import methods
 #' @include logging.R
-#' @slot KorAPUrl        URL of the web user interface of the KorAP server used in the connection.
-#' @slot apiVersion      requested KorAP API version.
-#' @slot indexRevision   indexRevision code as reported from API via `X-Index-Revision` HTTP header.
-#' @slot apiUrl          full URL of API including version.
-#' @slot accessToken     OAuth2 access token.
-#' @slot oauthClient     OAuth2 client object.
-#' @slot oauthScope      OAuth2 scope.
-#' @slot authorizationSupported logical that indicates if authorization is supported/necessary for the current KorAP instance. Automatically set during initialization.
-#' @slot userAgent       user agent string used for connection the API.
-#' @slot timeout         timeout in seconds for API requests (this does not influence server internal timeouts)
-#' @slot verbose         logical that decides whether operations will default to be verbose.
-#' @slot cache           logical that decides if API calls are cached locally.
-#' @slot welcome         list containing HTTP response received from KorAP server welcome function.
 
 #' @export
 KorAPConnection <- setClass("KorAPConnection", slots = c(KorAPUrl = "character", apiVersion = "character", indexRevision = "characterOrNULL", apiUrl = "character", accessToken = "characterOrNULL", oauthClient = "ANY", oauthScope = "characterOrNULL", authorizationSupported = "logical", userAgent = "character", timeout = "numeric", verbose = "logical", cache = "logical", welcome = "listOrNULL"))
@@ -37,6 +53,8 @@
 kustvakt_auth_path <- "settings/oauth/authorize"
 
 
+#' Initialize KorAPConnection object
+#' @keywords internal
 #' @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
@@ -110,7 +128,6 @@
 #' kq@collectedMatches$snippet
 #' }
 #'
-#' @rdname KorAPConnection-class
 
 #' @export
 setMethod("initialize", "KorAPConnection", function(.Object,
@@ -177,6 +194,7 @@
 
 #' Persist current access token in keyring
 #'
+#' @family initialization functions
 #' @param kco KorAPConnection object
 #' @param accessToken access token to be persisted. If not supplied, the current access token of the KorAPConnection object will be used.
 #' @return KorAPConnection object.
@@ -216,6 +234,7 @@
 
 #' Clear access token from keyring and KorAPConnection object
 #'
+#' @family initialization functions
 #' @aliases clearAccessToken
 #' @import keyring
 #' @param kco KorAPConnection object
@@ -249,6 +268,7 @@
 
 #' Authorize RKorAPClient
 #'
+#' @family initialization functions
 #' @aliases auth
 #'
 #' @description
@@ -367,8 +387,9 @@
 ## quiets concerns of R CMD check re: the .'s that appear in pipelines
 utils::globalVariables(c("."))
 
+#' Internal API call method
+#' @keywords internal
 #' @aliases apiCall
-#' @rdname KorAPConnection-class
 #' @param kco KorAPConnection object
 #' @param url request url
 #' @param json logical that determines if JSON result is expected
@@ -494,13 +515,13 @@
 setGeneric("clearCache", function(kco) standardGeneric("clearCache"))
 
 #' @aliases clearCache
-#' @rdname KorAPConnection-class
 #' @export
 setMethod("clearCache", "KorAPConnection", function(kco) {
   R.cache::clearCache(dir = KorAPCacheSubDir())
 })
 
-#' @rdname KorAPConnection-class
+#' Display KorAPConnection object
+#' @keywords internal
 #' @param object KorAPConnection object
 #' @export
 setMethod("show", "KorAPConnection", function(object) {
diff --git a/R/KorAPCorpusStats.R b/R/KorAPCorpusStats.R
index 7789945..5acba71 100644
--- a/R/KorAPCorpusStats.R
+++ b/R/KorAPCorpusStats.R
@@ -1,28 +1,40 @@
-#' Class KorAPCorpusStats
+#' KorAPCorpusStats class (internal)
 #'
-#' `KorAPCorpusStats` objects can hold information about a corpus or virtual corpus.
-#' `KorAPCorpusStats` objects can be obtained by the [corpusStats()] method.
+#' Internal class for corpus statistics storage. Users work with `corpusStats()` function instead.
 #'
+#' @keywords internal
 #' @include KorAPConnection.R
 #' @include logging.R
 #'
 #' @export
-#' @slot vc definition of the virtual corpus
-#' @slot tokens number of tokens
-#' @slot documents number of documents
-#' @slot sentences number of sentences
-#' @slot paragraphs number of paragraphs
-#' @slot webUIRequestUrl link to the web user interface with the current vc definition
 setClass("KorAPCorpusStats", slots = c(vc = "character", documents = "numeric", tokens = "numeric", sentences = "numeric", paragraphs = "numeric", webUIRequestUrl = "character"))
 
 setGeneric("corpusStats", function(kco, ...) standardGeneric("corpusStats"))
 
-#' Fetch information about a (virtual) corpus
+#' Get corpus size and statistics
+#'
+#' Retrieve information about corpus size (documents, tokens, sentences, paragraphs) 
+#' for the entire corpus or a virtual corpus subset.
+#'
+#' @section Usage:
+#' ```r
+#' # Get statistics for entire corpus
+#' kcon <- KorAPConnection()
+#' stats <- corpusStats(kcon)
+#' 
+#' # Get statistics for a specific time period
+#' stats <- corpusStats(kcon, "pubDate in 2020")
+#' 
+#' # Access the number of tokens
+#' stats@tokens
+#' ```
+#'
+#' @family corpus analysis
 #' @param kco [KorAPConnection()] object (obtained e.g. from `KorAPConnection()`
 #' @param vc string describing the virtual corpus. An empty string (default) means the whole corpus, as far as it is license-wise accessible.
 #' @param verbose logical. If `TRUE`, additional diagnostics are printed.
 #' @param as.df return result as data frame instead of as S4 object?
-#' @return `KorAPCorpusStats` object with the slots `documents`, `tokens`, `sentences`, `paragraphs`
+#' @return Object containing corpus statistics: `documents`, `tokens`, `sentences`, `paragraphs`
 #'
 #' @importFrom urltools url_encode
 #' @examples
diff --git a/R/KorAPQuery.R b/R/KorAPQuery.R
index f04e59d..9b77c39 100644
--- a/R/KorAPQuery.R
+++ b/R/KorAPQuery.R
@@ -1,9 +1,8 @@
-#' Class KorAPQuery
+#' KorAPQuery class (internal)
 #'
-#' This class provides methods to perform different kinds of queries on the KorAP API server.
-#' `KorAPQuery` objects, which are typically created by the [corpusQuery()] method,
-#' represent the current state of a query to a KorAP server.
+#' Internal class for query state management. Users work with `corpusQuery()`, `fetchAll()`, and `fetchNext()` instead.
 #'
+#' @keywords internal
 #' @include KorAPConnection.R
 #' @include logging.R
 #' @import httr2
@@ -25,9 +24,8 @@
   "hasMoreMatches"
 ))
 
-#' Method initialize
-#'
-#' @rdname KorAPQuery-class
+#' Initialize KorAPQuery object
+#' @keywords internal
 #' @param .Object …
 #' @param korapConnection KorAPConnection object
 #' @param request query part of the request URL
@@ -77,11 +75,11 @@
 ## quiets concerns of R CMD check re: the .'s that appear in pipelines
 utils::globalVariables(c("."))
 
-#' Corpus query
+#' Search corpus for query terms
 #'
 #' **`corpusQuery`** performs a corpus query via a connection to a KorAP-API-server
 #'
-#' @rdname KorAPQuery-class
+#' @family corpus search functions
 #' @aliases corpusQuery
 #'
 #' @importFrom urltools url_encode
@@ -383,6 +381,8 @@
 #'
 #' **`fetchNext`** fetches the next bunch of results of a KorAP query.
 #'
+#' @family corpus search functions
+#'
 #' @param kqo object obtained from [corpusQuery()]
 #' @param offset start offset for query results to fetch
 #' @param maxFetch maximum number of query results to fetch
@@ -403,7 +403,6 @@
 #' <https://ids-pub.bsz-bw.de/frontdoor/index/index/docId/9026>
 #'
 #' @aliases fetchNext
-#' @rdname KorAPQuery-class
 #' @importFrom dplyr rowwise mutate bind_rows select summarise n select
 #' @importFrom tibble enframe add_column
 #' @importFrom stringr word
@@ -698,6 +697,8 @@
 #'
 #' **`fetchAll`** fetches all results of a KorAP query.
 #'
+#' @family corpus search functions
+#'
 #' @examples
 #' \dontrun{
 #' # Fetch all metadata of every query hit for "Ameisenplage" and show a summary
@@ -723,7 +724,6 @@
 #' }
 #'
 #' @aliases fetchAll
-#' @rdname KorAPQuery-class
 #' @export
 setMethod("fetchAll", "KorAPQuery", function(kqo, verbose = kqo@korapConnection@verbose, ...) {
   return(fetchNext(kqo, offset = 0, maxFetch = NA, verbose = verbose, ...))
@@ -741,7 +741,6 @@
 #' }
 #'
 #' @aliases fetchRest
-#' @rdname KorAPQuery-class
 #' @export
 setMethod("fetchRest", "KorAPQuery", function(kqo, verbose = kqo@korapConnection@verbose, ...) {
   return(fetchNext(kqo, maxFetch = NA, verbose = verbose, ...))
@@ -754,6 +753,7 @@
 #' confidence intervals of one ore multiple search terms across one or multiple
 #' virtual corpora.
 #'
+#' @family frequency analysis
 #' @aliases frequencyQuery
 #' @examples
 #' \dontrun{
diff --git a/R/collocationAnalysis.R b/R/collocationAnalysis.R
index fe3ac2a..15daea9 100644
--- a/R/collocationAnalysis.R
+++ b/R/collocationAnalysis.R
@@ -3,6 +3,7 @@
 
 #' Collocation analysis
 #'
+#' @family collocation analysis functions
 #' @aliases collocationAnalysis
 #'
 #' @description
@@ -25,7 +26,6 @@
 #' This might lead to false negatives and to frequencies that differ from corresponding ones acquired via the web
 #' user interface.
 #'
-#' @family collocation analysis functions
 #'
 #' @param lemmatizeNodeQuery     if TRUE, node query will be lemmatized, i.e. `x -> [tt/l=x]`
 #' @param minOccur               minimum absolute number of observed co-occurrences to consider a collocate candidate
diff --git a/demo/frequency_by_country_highcharts.R b/demo/frequency_by_country_highcharts.R
index 5529e13..bf3bcdf 100644
--- a/demo/frequency_by_country_highcharts.R
+++ b/demo/frequency_by_country_highcharts.R
@@ -2,7 +2,7 @@
 library(highcharter)
 library(tidyverse)
 
-QUERIES <- c("[tt/l=verunfallen]", "Sonnabend") # search in treetagger lemma annotations
+QUERIES <- c("(das|einen|den) Cola") # search in treetagger lemma annotations
 COUNTRIES <- c("AT", "BE", "CH", "DE", "IT", "LU")
 
 VCS <- sprintf("textType=/Zeit.*/ & pubPlaceKey=%s", COUNTRIES) # limit virtual corpus to newspapers and magazines
diff --git a/demo/relativeTextpositionBoxplot.R b/demo/relativeTextpositionBoxplot.R
index 6bb71a1..8a7a3be 100644
--- a/demo/relativeTextpositionBoxplot.R
+++ b/demo/relativeTextpositionBoxplot.R
@@ -1,5 +1,4 @@
 library(RKorAPClient)
-library(highcharter)
 library(tidyverse)
 
 kco <- KorAPConnection(verbose = TRUE)
@@ -27,6 +26,7 @@
   "anfangs/i",
   "zuguterletzt/i",
   "zun\u00e4chst/i", # it is still necessary to encode non ascii characters in R package demos
+  "zuallererst/i",
   "zuerst/i",
   "zuletzt/i",
   "schlie\u00dflich/i"
diff --git a/man/KorAPConnection-class.Rd b/man/KorAPConnection-class.Rd
index 0637e39..591051f 100644
--- a/man/KorAPConnection-class.Rd
+++ b/man/KorAPConnection-class.Rd
@@ -4,171 +4,47 @@
 \name{KorAPConnection-class}
 \alias{KorAPConnection-class}
 \alias{KorAPConnection}
-\alias{initialize,KorAPConnection-method}
-\alias{apiCall,KorAPConnection-method}
-\alias{apiCall}
-\alias{clearCache,KorAPConnection-method}
-\alias{clearCache}
-\alias{show,KorAPConnection-method}
-\title{Class KorAPConnection}
-\usage{
-\S4method{initialize}{KorAPConnection}(
-  .Object,
-  KorAPUrl = if (is.null(Sys.getenv("KORAP_URL")) | Sys.getenv("KORAP_URL") == "") {
-    
-    "https://korap.ids-mannheim.de/"
- } else {
-     Sys.getenv("KORAP_URL")
- },
-  apiVersion = "v1.0",
-  apiUrl,
-  accessToken = getAccessToken(KorAPUrl),
-  oauthClient = NULL,
-  oauthScope = "search match_info",
-  authorizationSupported = TRUE,
-  userAgent = "R-KorAP-Client",
-  timeout = 240,
-  verbose = FALSE,
-  cache = TRUE
-)
-
-\S4method{apiCall}{KorAPConnection}(
-  kco,
-  url,
-  json = TRUE,
-  getHeaders = FALSE,
-  cache = kco@cache,
-  timeout = kco@timeout
-)
-
-\S4method{clearCache}{KorAPConnection}(kco)
-
-\S4method{show}{KorAPConnection}(object)
-}
-\arguments{
-\item{.Object}{KorAPConnection object}
-
-\item{KorAPUrl}{URL of the web user interface of the KorAP server instance you want to access.
-Defaults to the environment variable \code{KORAP_URL} if set and to the IDS Mannheim KorAP main instance
-to query DeReKo, otherwise.}
-
-\item{apiVersion}{which version of KorAP's API you want to connect to.}
-
-\item{apiUrl}{URL of the KorAP web service.}
-
-\item{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
-\href{https://github.com/KorAP/RKorAPClient#authorization}{authorization section}
-of the RKorAPClient Readme on GitHub.
-
-To use authorization based on an access token
-in subsequent queries, initialize your KorAP connection with:
-
-\if{html}{\out{<div class="sourceCode">}}\preformatted{kco <- KorAPConnection(accessToken="<access token>")
-}\if{html}{\out{</div>}}
-
-In order to make the API
-token persistent for the currently used \code{KorAPUrl} (you can have one
-token per KorAPUrl / KorAP server instance), use:
-
-\if{html}{\out{<div class="sourceCode">}}\preformatted{persistAccessToken(kco)
-}\if{html}{\out{</div>}}
-
-This will store it in your keyring using the
-\link[keyring:keyring-package]{keyring::keyring-package}. Subsequent KorAPConnection() calls will
-then automatically retrieve the token from your keying. To stop using a
-persisted token, call \code{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 \code{kco <- KorAPConnection(cache=FALSE)} or use
-\code{\link[=clearCache]{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 \code{\link[=auth]{auth()}} method.}
-
-\item{oauthClient}{OAuth2 client object.}
-
-\item{oauthScope}{OAuth2 scope.}
-
-\item{authorizationSupported}{logical that indicates if authorization is supported/necessary for the current KorAP instance. Automatically set during initialization.}
-
-\item{userAgent}{user agent string.}
-
-\item{timeout}{tineout in seconds for API requests (this does not influence server internal timeouts).}
-
-\item{verbose}{logical that decides whether following operations will default to
-be verbose.}
-
-\item{cache}{logical that decides if API calls are cached locally. You can clear
-the cache with \code{\link[=clearCache]{clearCache()}}.}
-
-\item{kco}{KorAPConnection object}
-
-\item{url}{request url}
-
-\item{json}{logical that determines if JSON result is expected}
-
-\item{getHeaders}{logical that determines if headers and content should be returned (as a list)}
-
-\item{object}{KorAPConnection object}
-}
-\value{
-\code{\link[=KorAPConnection]{KorAPConnection()}} object that can be used e.g. with
-\code{\link[=corpusQuery]{corpusQuery()}}
-}
+\title{Connect to KorAP Server}
 \description{
-\code{KorAPConnection} objects represent the connection to a KorAP server.
-New \code{KorAPConnection} objects can be created by \code{KorAPConnection()}.
+\code{KorAPConnection()} creates a connection to a KorAP server for corpus queries.
+This is your starting point for all corpus analysis tasks.
 }
-\section{Slots}{
+\details{
+Use \code{KorAPConnection()} to connect, then \code{corpusQuery()} to search, and
+\code{fetchAll()} to retrieve results. For authorized access to restricted corpora,
+use \code{auth()} or provide an \code{accessToken}.
 
-\describe{
-\item{\code{KorAPUrl}}{URL of the web user interface of the KorAP server used in the connection.}
+The KorAPConnection object contains various configuration slots for advanced users:
+KorAPUrl (server URL), apiVersion, accessToken (OAuth2 token),
+timeout (request timeout), verbose (logging), cache (local caching),
+and other technical parameters. Most users can ignore these implementation details.
+}
+\section{Basic Workflow}{
 
-\item{\code{apiVersion}}{requested KorAP API version.}
 
-\item{\code{indexRevision}}{indexRevision code as reported from API via \code{X-Index-Revision} HTTP header.}
+\if{html}{\out{<div class="sourceCode r">}}\preformatted{# Connect to KorAP
+kcon <- KorAPConnection()
 
-\item{\code{apiUrl}}{full URL of API including version.}
+# Search for a term
+query <- corpusQuery(kcon, "Ameisenplage")
 
-\item{\code{accessToken}}{OAuth2 access token.}
-
-\item{\code{oauthClient}}{OAuth2 client object.}
-
-\item{\code{oauthScope}}{OAuth2 scope.}
-
-\item{\code{authorizationSupported}}{logical that indicates if authorization is supported/necessary for the current KorAP instance. Automatically set during initialization.}
-
-\item{\code{userAgent}}{user agent string used for connection the API.}
-
-\item{\code{timeout}}{timeout in seconds for API requests (this does not influence server internal timeouts)}
-
-\item{\code{verbose}}{logical that decides whether operations will default to be verbose.}
-
-\item{\code{cache}}{logical that decides if API calls are cached locally.}
-
-\item{\code{welcome}}{list containing HTTP response received from KorAP server welcome function.}
-}}
-
-\examples{
-\dontrun{
-
-kcon <- KorAPConnection(verbose = TRUE)
-kq <- corpusQuery(kcon, "Ameisenplage")
-kq <- fetchAll(kq)
+# Get all results
+results <- fetchAll(query)
+}\if{html}{\out{</div>}}
 }
 
-\dontrun{
+\section{Authorization}{
 
-kcon <- KorAPConnection(verbose = TRUE, accessToken = "e739u6eOzkwADQPdVChxFg")
-kq <- corpusQuery(kcon, "Ameisenplage", metadataOnly = FALSE)
-kq <- fetchAll(kq)
-kq@collectedMatches$snippet
+For access to restricted corpora, authorize your connection:
+
+\if{html}{\out{<div class="sourceCode r">}}\preformatted{kcon <- KorAPConnection() |> auth()
+}\if{html}{\out{</div>}}
 }
 
+\seealso{
+Other initialization functions: 
+\code{\link{auth,KorAPConnection-method}},
+\code{\link{clearAccessToken,KorAPConnection-method}},
+\code{\link{persistAccessToken,KorAPConnection-method}}
 }
+\concept{initialization functions}
diff --git a/man/KorAPCorpusStats-class.Rd b/man/KorAPCorpusStats-class.Rd
index b725ee4..a6bb55f 100644
--- a/man/KorAPCorpusStats-class.Rd
+++ b/man/KorAPCorpusStats-class.Rd
@@ -4,7 +4,7 @@
 \name{KorAPCorpusStats-class}
 \alias{KorAPCorpusStats-class}
 \alias{show,KorAPCorpusStats-method}
-\title{Class KorAPCorpusStats}
+\title{KorAPCorpusStats class (internal)}
 \usage{
 \S4method{show}{KorAPCorpusStats}(object)
 }
@@ -12,22 +12,6 @@
 \item{object}{KorAPCorpusStats object}
 }
 \description{
-\code{KorAPCorpusStats} objects can hold information about a corpus or virtual corpus.
-\code{KorAPCorpusStats} objects can be obtained by the \code{\link[=corpusStats]{corpusStats()}} method.
+Internal class for corpus statistics storage. Users work with \code{corpusStats()} function instead.
 }
-\section{Slots}{
-
-\describe{
-\item{\code{vc}}{definition of the virtual corpus}
-
-\item{\code{tokens}}{number of tokens}
-
-\item{\code{documents}}{number of documents}
-
-\item{\code{sentences}}{number of sentences}
-
-\item{\code{paragraphs}}{number of paragraphs}
-
-\item{\code{webUIRequestUrl}}{link to the web user interface with the current vc definition}
-}}
-
+\keyword{internal}
diff --git a/man/KorAPQuery-class.Rd b/man/KorAPQuery-class.Rd
index b4c8e87..b35cb45 100644
--- a/man/KorAPQuery-class.Rd
+++ b/man/KorAPQuery-class.Rd
@@ -4,71 +4,12 @@
 \name{KorAPQuery-class}
 \alias{KorAPQuery-class}
 \alias{KorAPQuery}
-\alias{initialize,KorAPQuery-method}
-\alias{corpusQuery,KorAPConnection-method}
-\alias{corpusQuery}
-\alias{fetchNext,KorAPQuery-method}
-\alias{fetchNext}
-\alias{fetchAll,KorAPQuery-method}
-\alias{fetchAll}
-\alias{fetchRest,KorAPQuery-method}
-\alias{fetchRest}
 \alias{buildWebUIRequestUrlFromString}
 \alias{buildWebUIRequestUrl}
 \alias{format.KorAPQuery}
 \alias{show,KorAPQuery-method}
-\title{Class KorAPQuery}
+\title{KorAPQuery class (internal)}
 \usage{
-\S4method{initialize}{KorAPQuery}(
-  .Object,
-  korapConnection = NULL,
-  request = NULL,
-  vc = "",
-  totalResults = 0,
-  nextStartIndex = 0,
-  fields = c("corpusSigle", "textSigle", "pubDate", "pubPlace", "availability",
-    "textClass", "snippet", "tokens"),
-  requestUrl = "",
-  webUIRequestUrl = "",
-  apiResponse = NULL,
-  hasMoreMatches = FALSE,
-  collectedMatches = NULL
-)
-
-\S4method{corpusQuery}{KorAPConnection}(
-  kco,
-  query = if (missing(KorAPUrl)) {
-    
-    stop("At least one of the parameters query and KorAPUrl must be specified.", call. =
-    FALSE)
- } else {
-     httr2::url_parse(KorAPUrl)$query$q
- },
-  vc = if (missing(KorAPUrl)) "" else httr2::url_parse(KorAPUrl)$query$cq,
-  KorAPUrl,
-  metadataOnly = TRUE,
-  ql = if (missing(KorAPUrl)) "poliqarp" else httr2::url_parse(KorAPUrl)$query$ql,
-  fields = c("corpusSigle", "textSigle", "pubDate", "pubPlace", "availability",
-    "textClass", "snippet", "tokens"),
-  accessRewriteFatal = TRUE,
-  verbose = kco@verbose,
-  expand = length(vc) != length(query),
-  as.df = FALSE,
-  context = NULL
-)
-
-\S4method{fetchNext}{KorAPQuery}(
-  kqo,
-  offset = kqo@nextStartIndex,
-  maxFetch = maxResultsPerPage,
-  verbose = kqo@korapConnection@verbose,
-  randomizePageOrder = FALSE
-)
-
-\S4method{fetchAll}{KorAPQuery}(kqo, verbose = kqo@korapConnection@verbose, ...)
-
-\S4method{fetchRest}{KorAPQuery}(kqo, verbose = kqo@korapConnection@verbose, ...)
-
 buildWebUIRequestUrlFromString(KorAPUrl, query, vc = "", ql = "poliqarp")
 
 buildWebUIRequestUrl(
@@ -90,179 +31,13 @@
 \S4method{show}{KorAPQuery}(object)
 }
 \arguments{
-\item{.Object}{…}
-
-\item{korapConnection}{KorAPConnection object}
-
-\item{request}{query part of the request URL}
-
-\item{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.}
-
-\item{totalResults}{number of hits the query has yielded}
-
-\item{nextStartIndex}{at what index to start the next fetch of query results}
-
-\item{fields}{(meta)data fields that will be fetched for every match.}
-
-\item{requestUrl}{complete URL of the API request}
-
-\item{webUIRequestUrl}{URL of a web frontend request corresponding to the API request}
-
-\item{apiResponse}{data-frame representation of the JSON response of the API request}
-
-\item{hasMoreMatches}{logical that signals if more query results can be fetched}
-
-\item{collectedMatches}{matches already fetched from the KorAP-API-server}
-
-\item{kco}{\code{\link[=KorAPConnection]{KorAPConnection()}} object (obtained e.g. from \code{KorAPConnection()}}
-
-\item{query}{string that contains the corpus query. The query language depends on the \code{ql} parameter. Either \code{query} must be provided or \code{KorAPUrl}.}
-
-\item{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 \code{KorAPConnection}) to provide all necessary information for the query.}
-
-\item{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
-\href{https://github.com/KorAP/RKorAPClient#authorization}{authorization section}
-of the RKorAPClient Readme on GitHub and set the \code{metadataOnly} parameter to
-\code{FALSE}.}
-
-\item{ql}{string to choose the query language (see \href{https://github.com/KorAP/Kustvakt/wiki/Service:-Search-GET#user-content-parameters}{section on Query Parameters} in the Kustvakt-Wiki for possible values.}
-
-\item{accessRewriteFatal}{abort if query or given vc had to be rewritten due to insufficient rights (not yet implemented).}
-
-\item{verbose}{print progress information if true}
-
-\item{expand}{logical that decides if \code{query} and \code{vc} parameters are expanded to all of their combinations. Defaults to \code{TRUE}, iff \code{query} and \code{vc} have different lengths}
-
-\item{as.df}{return result as data frame instead of as S4 object?}
-
-\item{context}{string that specifies the size of the left and the right context returned in \code{snippet}
-(provided that \code{metadataOnly} is set to \code{false} and that the necessary access right are  met).
-The format of the context size specifcation (e.g. \verb{3-token,3-token}) is described in the \href{https://github.com/KorAP/Kustvakt/wiki/Service:-Search-GET}{Service: Search GET documentation of the Kustvakt Wiki}.
-If the parameter is not set, the default context size secification of the KorAP server instance will be used.
-Note that you cannot overrule the maximum context size set in the KorAP server instance,
-as this is typically legally motivated.}
-
-\item{kqo}{object obtained from \code{\link[=corpusQuery]{corpusQuery()}}}
-
-\item{offset}{start offset for query results to fetch}
-
-\item{maxFetch}{maximum number of query results to fetch}
-
-\item{randomizePageOrder}{fetch result pages in pseudo random order if true. Use \code{\link[=set.seed]{set.seed()}} to set seed for reproducible results.}
+\item{x}{KorAPQuery object}
 
 \item{...}{further arguments passed to or from other methods}
 
-\item{x}{KorAPQuery object}
-
 \item{object}{KorAPQuery object}
 }
-\value{
-Depending on the \code{as.df} parameter, a tibble or a \code{\link[=KorAPQuery]{KorAPQuery()}} object that, among other information, contains the total number of results in \verb{@totalResults}. The resulting object can be used to fetch all query results (with \code{\link[=fetchAll]{fetchAll()}}) or the next page of results (with \code{\link[=fetchNext]{fetchNext()}}).
-A corresponding URL to be used within a web browser is contained in \verb{@webUIRequestUrl}
-Please make sure to check \verb{$collection$rewrites} to see if any unforeseen access rewrites of the query's virtual corpus had to be performed.
-
-The \code{kqo} input object with updated slots \code{collectedMatches}, \code{apiResponse}, \code{nextStartIndex}, \code{hasMoreMatches}
-}
 \description{
-This class provides methods to perform different kinds of queries on the KorAP API server.
-\code{KorAPQuery} objects, which are typically created by the \code{\link[=corpusQuery]{corpusQuery()}} method,
-represent the current state of a query to a KorAP server.
-
-\strong{\code{corpusQuery}} performs a corpus query via a connection to a KorAP-API-server
-
-\strong{\code{fetchNext}} fetches the next bunch of results of a KorAP query.
-
-\strong{\code{fetchAll}} fetches all results of a KorAP query.
+Internal class for query state management. Users work with \code{corpusQuery()}, \code{fetchAll()}, and \code{fetchNext()} instead.
 }
-\examples{
-\dontrun{
-
-# Fetch metadata of every query hit for "Ameisenplage" and show a summary
-KorAPConnection() \%>\%
-  corpusQuery("Ameisenplage") \%>\%
-  fetchAll()
-}
-
-\dontrun{
-
-# Use the copy of a KorAP-web-frontend URL for an API query of "Ameise" in a virtual corpus
-# and show the number of query hits (but don't fetch them).
-
-KorAPConnection(verbose = TRUE) \%>\%
-  corpusQuery(
-    KorAPUrl =
-      "https://korap.ids-mannheim.de/?q=Ameise&cq=pubDate+since+2017&ql=poliqarp"
-  )
-}
-
-\dontrun{
-
-# Plot the time/frequency curve of "Ameisenplage"
-KorAPConnection(verbose = TRUE) \%>\%
-  {
-    . ->> kco
-  } \%>\%
-  corpusQuery("Ameisenplage") \%>\%
-  fetchAll() \%>\%
-  slot("collectedMatches") \%>\%
-  mutate(year = lubridate::year(pubDate)) \%>\%
-  dplyr::select(year) \%>\%
-  group_by(year) \%>\%
-  summarise(Count = dplyr::n()) \%>\%
-  mutate(Freq = mapply(function(f, y) {
-    f / corpusStats(kco, paste("pubDate in", y))@tokens
-  }, Count, year)) \%>\%
-  dplyr::select(-Count) \%>\%
-  complete(year = min(year):max(year), fill = list(Freq = 0)) \%>\%
-  plot(type = "l")
-}
-\dontrun{
-
-q <- KorAPConnection() \%>\%
-  corpusQuery("Ameisenplage") \%>\%
-  fetchNext()
-q@collectedMatches
-}
-
-\dontrun{
-# Fetch all metadata of every query hit for "Ameisenplage" and show a summary
-q <- KorAPConnection() |>
-  corpusQuery("Ameisenplage") |>
-  fetchAll()
-q@collectedMatches
-
-# Fetch also all KWICs
-q <- KorAPConnection() |> auth() |>
- corpusQuery("Ameisenplage", metadataOnly = FALSE) |>
- fetchAll()
-q@collectedMatches
-
-# Retrieve title and text sigle metadata of all texts published on 1958-03-12
-q <- KorAPConnection() |>
- corpusQuery("<base/s=t>", # this matches each text once
-    vc = "pubDate in 1958-03-12",
-    fields = c("textSigle", "title"),
-) |>
- fetchAll()
-q@collectedMatches
-}
-
-\dontrun{
-
-q <- KorAPConnection() \%>\%
-  corpusQuery("Ameisenplage") \%>\%
-  fetchRest()
-q@collectedMatches
-}
-
-}
-\references{
-\url{https://ids-pub.bsz-bw.de/frontdoor/index/index/docId/9026}
-
-\url{https://ids-pub.bsz-bw.de/frontdoor/index/index/docId/9026}
-}
-\seealso{
-\code{\link[=KorAPConnection]{KorAPConnection()}}, \code{\link[=fetchNext]{fetchNext()}}, \code{\link[=fetchRest]{fetchRest()}}, \code{\link[=fetchAll]{fetchAll()}}, \code{\link[=corpusStats]{corpusStats()}}
-}
+\keyword{internal}
diff --git a/man/auth-KorAPConnection-method.Rd b/man/auth-KorAPConnection-method.Rd
index 3e8d336..5c36452 100644
--- a/man/auth-KorAPConnection-method.Rd
+++ b/man/auth-KorAPConnection-method.Rd
@@ -40,4 +40,10 @@
 }
 \seealso{
 \code{\link[=persistAccessToken]{persistAccessToken()}}, \code{\link[=clearAccessToken]{clearAccessToken()}}
+
+Other initialization functions: 
+\code{\link{KorAPConnection-class}},
+\code{\link{clearAccessToken,KorAPConnection-method}},
+\code{\link{persistAccessToken,KorAPConnection-method}}
 }
+\concept{initialization functions}
diff --git a/man/clearAccessToken-KorAPConnection-method.Rd b/man/clearAccessToken-KorAPConnection-method.Rd
index ecc7570..0e0c450 100644
--- a/man/clearAccessToken-KorAPConnection-method.Rd
+++ b/man/clearAccessToken-KorAPConnection-method.Rd
@@ -25,4 +25,10 @@
 }
 \seealso{
 \code{\link[=persistAccessToken]{persistAccessToken()}}
+
+Other initialization functions: 
+\code{\link{KorAPConnection-class}},
+\code{\link{auth,KorAPConnection-method}},
+\code{\link{persistAccessToken,KorAPConnection-method}}
 }
+\concept{initialization functions}
diff --git a/man/corpusStats-KorAPConnection-method.Rd b/man/corpusStats-KorAPConnection-method.Rd
index 961d64b..31d1c87 100644
--- a/man/corpusStats-KorAPConnection-method.Rd
+++ b/man/corpusStats-KorAPConnection-method.Rd
@@ -3,7 +3,7 @@
 \name{corpusStats,KorAPConnection-method}
 \alias{corpusStats,KorAPConnection-method}
 \alias{corpusStats}
-\title{Fetch information about a (virtual) corpus}
+\title{Get corpus size and statistics}
 \usage{
 \S4method{corpusStats}{KorAPConnection}(kco, vc = "", verbose = kco@verbose, as.df = FALSE)
 }
@@ -17,11 +17,27 @@
 \item{as.df}{return result as data frame instead of as S4 object?}
 }
 \value{
-\code{KorAPCorpusStats} object with the slots \code{documents}, \code{tokens}, \code{sentences}, \code{paragraphs}
+Object containing corpus statistics: \code{documents}, \code{tokens}, \code{sentences}, \code{paragraphs}
 }
 \description{
-Fetch information about a (virtual) corpus
+Retrieve information about corpus size (documents, tokens, sentences, paragraphs)
+for the entire corpus or a virtual corpus subset.
 }
+\section{Usage}{
+
+
+\if{html}{\out{<div class="sourceCode r">}}\preformatted{# Get statistics for entire corpus
+kcon <- KorAPConnection()
+stats <- corpusStats(kcon)
+
+# Get statistics for a specific time period
+stats <- corpusStats(kcon, "pubDate in 2020")
+
+# Access the number of tokens
+stats@tokens
+}\if{html}{\out{</div>}}
+}
+
 \examples{
 \dontrun{
 
@@ -30,3 +46,4 @@
 }
 
 }
+\concept{corpus analysis}
diff --git a/man/frequencyQuery-KorAPConnection-method.Rd b/man/frequencyQuery-KorAPConnection-method.Rd
index 9f934e6..cc9c361 100644
--- a/man/frequencyQuery-KorAPConnection-method.Rd
+++ b/man/frequencyQuery-KorAPConnection-method.Rd
@@ -54,3 +54,4 @@
 }
 
 }
+\concept{frequency analysis}
diff --git a/man/persistAccessToken-KorAPConnection-method.Rd b/man/persistAccessToken-KorAPConnection-method.Rd
index 4e539d7..898fc3e 100644
--- a/man/persistAccessToken-KorAPConnection-method.Rd
+++ b/man/persistAccessToken-KorAPConnection-method.Rd
@@ -31,4 +31,10 @@
 }
 \seealso{
 \code{\link[=clearAccessToken]{clearAccessToken()}}, \code{\link[=auth]{auth()}}
+
+Other initialization functions: 
+\code{\link{KorAPConnection-class}},
+\code{\link{auth,KorAPConnection-method}},
+\code{\link{clearAccessToken,KorAPConnection-method}}
 }
+\concept{initialization functions}