Search code examples
kotlinkotlin-dokka

Is there a convention for documenting Lambdas as a function parameter in KDoc?

I'm writing a Kotlin function which takes a lambda as a parameter, like

fun someFunction( param1: (value1: Boolean, value2: Boolean) -> Unit )

I'm wondering if there's a way to document the function as input, so I can reference value1 or value2 in the documentation?

So far doing

/**
* Documentation for someFunction
* @param param1 Takes a function where [value1] is some value
*/
fun someFunction( param1: (value1: Boolean, value2: Boolean) -> Unit )

hasn't worked, dokka will simply fail to build docs.

Solution

  • One way to do this, though not as straightforward as simply putting a paragraph in the docs, is extracting the function type into a typealias and documenting the semantics of the function in the KDoc of the type alias.

    The downside is that the IDE cannot resolve the functional type's declared parameters in the KDoc for the functional type alias either.

    For example:

    /**
 * Documentation for the contract of this usage of the functional type.
 * @param value1 or [value1], unfortunately, won't work in the IDE just yet.
 */
typealias SomeEventHandler = (value1: Boolean, value2: Boolean) -> Unit

/**
* Documentation for someFunction
* @param param1 Some docs on this specific usage of [SomeEventHandler]
*/
fun someFunction(param1: SomeEventHandler)

    Given how type aliases work, the function transformed this way will still also accept "normal" instances of the functional type (Boolean, Boolean) -> Unit.