How do I document complex function parameters in my own R package?

I am currently transforming my big R-Project into a package and I am trying to document it properly with enough examples and tests.

Some of my functions use parameters that are of a complex type like a list of two dataframes. I don't want to seperate them into two parameters as they belong together and can not be changed independently. How do I deal with that, that means:

1. How do I describe this parameter in the function parameter description? Should every necessary dataframe and every necessary column of the dataframes be mentioned and described here or is there a better place?

2. How do I create a good example and a good test for this function? Is it common to put an example for this complex parameter into the data-subdirectory, so it can be used in the function example?

There is a lot of flexibility in how you document function parameters in R. The checks will complain if you give no documentation, but they don't enforce a style or details.

What I find most useful is for the individual parameter descriptions to be quite short, with expanded details in the Details section (as @Bart suggested) or in a Note, or in a separate help page. For example, you might have something like this in your Rd file:

\arguments{
  \item{arg1}{
A list containing model information.  See Details below.
}
  \item{arg2}{
A model object of class \code{\link{modelObject}}
}
}
\details{
Argument \code{arg1} is a list containing two components:
\describe{
\item{first}{This is the first component}
\item{second}{This is the second component}
}

If you are using Roxygen you'd put similar text in your Roxygen comments and it would build the Rd file for you.

For examples, you can either create data in the example, use a standard dataset, or read one of your own. If you do use your own data, don't store a complex structure, store simple data in a format that a user might have, and then show how to build the complex structure in the example code.