Support documenting context parameters

[whyoleg]

Currently it's possible to document function parameters via @param and receiver of function/property via @receiver:

/**
 * @receiver documentation for receiver of type [String]
 * @param number documentation for parameter with name [number]
 */
fun String.test(number: Int)

The same should be possible for context parameters.

There are two options on how it could work:

1. new tag @context - context parameters have a separate tag, similar to receiver. As context parameters have different meaning, and most likely should be represented in different section of documentation - separate from Parameters section, it might make sense to have separate tag. In this case receiver, function parameters and context parameters will have three different tags.

/**
 * @context scope documentation for context parameter
 * @receiver documentation for receiver of type [String]
 * @param number documentation for parameter with name [number]
 */
context(scope: Scope)
fun String.test(number: Int)

2. reusing @param - context parameters are treated similar to ordinary parameters. But it's still make sense to show them separately in documentation.

/**
 * @param scope documentation for context parameter
 * @receiver documentation for receiver of type [String]
 * @param number documentation for parameter with name [number]
 */
context(scope: Scope)
fun String.test(number: Int)

Bonus (questionable) option: use @param for referencing both context parameters, function parameters and receiver. In KDoc it's possible to use [this] to reference receiver of function/property in the way it's possible to reference named parameters in documentation:

/**
 * when calling function, [this] should be longer than [number] symbols
 */
fun String.test(number: Int)

With this possibility in mind, it could be possible to replace @receiver tag with @param this:

/**
 * @param scope documentation for context parameter
 * @param this documentation for receiver of type [String]
 * @param number documentation for parameter with name [number]
 */
context(scope: Scope)
fun String.test(number: Int)

Or with brackets:

/**
 * @param[scope] documentation for context parameter
 * @param[this] documentation for receiver of type [String]
 * @param[number] documentation for parameter with name [number]
 */
context(scope: Scope)
fun String.test(number: Int)

In this case @receiver tag could be deprecated (or gradually phased out) and both referencing and documenting receiver will have same syntax