-
Notifications
You must be signed in to change notification settings - Fork 471
Open
Labels
enhancementAn issue for a feature or an overall improvementAn issue for a feature or an overall improvementkdoc-specAn issue that requires clarification from the KDoc spec's perspectiveAn issue that requires clarification from the KDoc spec's perspectivetopic: K2Issues / PRs that are related to the K2 migration. See #2888Issues / PRs that are related to the K2 migration. See #2888
Description
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:
- 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 fromParameterssection, 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)- 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
Metadata
Metadata
Assignees
Labels
enhancementAn issue for a feature or an overall improvementAn issue for a feature or an overall improvementkdoc-specAn issue that requires clarification from the KDoc spec's perspectiveAn issue that requires clarification from the KDoc spec's perspectivetopic: K2Issues / PRs that are related to the K2 migration. See #2888Issues / PRs that are related to the K2 migration. See #2888