Add KDoc for KtWhenExpression.getMissingCases()
KtWhenExpression.getMissingCases() reports the same missing cases even
when the KtWhenExpression has an else branch. Without a description, it
is difficult to be aware of it.
diff --git a/analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/components/KtExpressionInfoProvider.kt b/analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/components/KtExpressionInfoProvider.kt
index 4507dd2..450b8c3 100644
--- a/analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/components/KtExpressionInfoProvider.kt
+++ b/analysis/analysis-api/src/org/jetbrains/kotlin/analysis/api/components/KtExpressionInfoProvider.kt
@@ -22,6 +22,24 @@
public fun KtReturnExpression.getReturnTargetSymbol(): KtCallableSymbol? =
withValidityAssertion { analysisSession.expressionInfoProvider.getReturnExpressionTargetSymbol(this) }
+ /**
+ * Returns cases missing from the branches of [KtWhenExpression].
+ *
+ * The missing cases of the when-expression in the following example are Direction.WEST and Direction.EAST:
+ *
+ * enum class Direction {
+ * NORTH, SOUTH, WEST, EAST
+ * }
+ * foo = when(direction) {
+ * Direction.NORTH -> 1
+ * Direction.SOUTH -> 2
+ * else -> 3
+ * }
+ *
+ * Note that this function returns the same missing cases regardless of the existence of the else branch.
+ * If you have to assume that it does not have the missing cases when it has an else branch,
+ * you need a separate check whether it has an else branch or not.
+ */
public fun KtWhenExpression.getMissingCases(): List<WhenMissingCase> =
withValidityAssertion { analysisSession.expressionInfoProvider.getWhenMissingCases(this) }
