tree e5fcf010d0c8deb3ba9437a43e4c7ce2676a1576
parent 6a0bad4e589d158c409b50238f51c4d6868bc230
author Marc Kupietz <kupietz@ids-mannheim.de> 1788204961 +0200
committer Marc Kupietz <kupietz@ids-mannheim.de> 1788204963 +0200

Document KorAPConnection() as a function to fix CRAN Rd NOTE

CRAN's r-devel-linux-x86_64-debian-gcc and -clang checks report

  Rd files without \usage:
    'KorAPConnection-class.Rd'
  \arguments should not be documented without \usage.

because the user facing documentation, with one @param per constructor
argument, was attached to the setClass() call. The object exported under
the name KorAPConnection was the class generator, whose formals are just
`function(...)`, so roxygen2 could not derive a \usage section from it
and the documented arguments ended up in an Rd file without one. Adding
a hand written \usage is not an option either: it contradicts the
generator's `...` signature and turns the NOTE into a much worse
"code/documentation mismatches" WARNING.

Replace the generator with a real KorAPConnection() function that
forwards its arguments to new("KorAPConnection", ...) and attach the
documentation to it. roxygen2 now derives \usage from the actual
formals, so the manual page states how the constructor is really called,
and the NOTE is gone.

The constructor forwards supplied arguments only, so that the defaults
and the missing() based KORAP_VERBOSE / rkorap.verbose overrides of the
initialize method keep working unchanged. Its own defaults merely mirror
those of the initialize method in order to document them; the new tests
asserts that the documented defaults are the ones a connection actually
ends up with, so that the two cannot drift apart silently. The KORAP_URL
default is now shared by both signatures as defaultKorAPUrl().

NAMESPACE is unchanged: KorAPConnection remains both an exported
function and an exported S4 class, and new("KorAPConnection", ...) keeps
working.

R CMD check --as-cran: Status OK, and no Rd file in man/ has \arguments
without \usage any more.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Change-Id: I789d42c01e1be98a989f8f4d9a5b14865ca48daa