[python] Add javadoc for PyTypeVarTupleType, PyUnpackedTupleType and PyVariadicType

GitOrigin-RevId: 29670649bf511958d1d6a935a4c90429c378b928

python/python-psi-api/src/com/jetbrains/python/psi/types/PyTypeVarTupleType.java

@@ -1,5 +1,27 @@
 // Copyright 2000-2023 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
 package com.jetbrains.python.psi.types;
 
+/**
+ * Represents a variadic type parameter that can be substituted with an arbitrary number of types in the corresponding generic type.
+ * A series of concrete types it can be replaced with is normally represented with {@link PyUnpackedTupleType}.
+ * <p>
+ * It's declared either using the {@code TypeVarTuple} function from the "typing" module, as in
+ * <pre>{@code
+ * from typing import TypeVar
+ *
+ * Ts = TypeVarTuple('Ts')
+ *
+ * class MyGeneric(Generic[*Ts]):
+ *     ...
+ * }</pre>
+ * or inline, without any imports, with the new syntax for generic classes and type aliases introduced in PEP 695, as in
+ * <pre>{@code
+ * class MyGeneric[*Ts]:
+ *     ...
+ * }</pre>
+ *
+ * @see <a href="https://peps.python.org/pep-0646/#type-variable-tuples">PEP 646 – Variadic Generics</a>
+ * @see PyUnpackedTupleType
+ */
 public interface PyTypeVarTupleType extends PyTypeParameterType, PyVariadicType {
 }

python/python-psi-api/src/com/jetbrains/python/psi/types/PyUnpackedTupleType.java

@@ -5,8 +5,39 @@ import org.jetbrains.annotations.NotNull;
 
 import java.util.List;
 
+/**
+ * Represents an ordered series of types, or an unbound repetition of a single type.
+ * <p>
+ * It can be thought of as a content of a standard tuple type, but not associated with the corresponding built-in class.
+ * An unpacked tuple can appear only inside other types, such as types of generic classes and callables.
+ * Unpacked tuple types serve as concrete substitutions for TypeVarTuples in the result of type inference.
+ * <p>
+ * An unpacked tuple type can be declared with {@code *tuple[T1, T2, ...]} syntax.
+ *
+ * @see <a href="https://peps.python.org/pep-0646/#unpacking-tuple-types">PEP 646 – Variadic Generics</a>
+ * @see PyTypeVarTupleType
+ */
 public interface PyUnpackedTupleType extends PyVariadicType {
+  /**
+   * Returns types contained inside this unpacked tuple type.
+   * <p>
+   * For an unbound unpacked tuple type, the result is always a single type, e.g. for {@code *tuple[int, ...]} the returned
+   * list will consist only of a {@link PyClassType} for the built-in class int.
+   * <p>
+   * The contained types are not flattened, e.g. for {@code *tuple[*tuple[int, str], str]} the list will
+   * contain two types {@link PyUnpackedTupleType} for {@code *tuple[int, str]} and {@link PyClassType} for {@code str}.
+   */
   @NotNull List<PyType> getElementTypes();
 
+  /**
+   * Returns true if this unpacked tuple type represents an unlimited repetition of a single type as opposed to
+   * a finite series of types.
+   * <p>
+   * Such unpacked tuples types are declared with the syntax {@code *tuple[T, ...]}.
+   * <p>
+   * Note that inner variadic types are not considered, i.e. in {@code *tuple[int, *tuple[str, ...]]} or {@code *tuple[*Ts]}
+   * the top-level unpacked tuple type is still considered bound or "concrete", even though it represents a
+   * tuple of types of unknown length.
+   */
   boolean isUnbound();
 }

python/python-psi-api/src/com/jetbrains/python/psi/types/PyVariadicType.java

@@ -14,6 +14,15 @@ import org.jetbrains.annotations.Nullable;
 
 import java.util.List;
 
+/**
+ * A marker interface for type forms that can be "unpacked" into a series of types.
+ * Normally, such constructs cannot be used on their own in type hints, and can appear only inside other generic types.
+ * Two variants of such types described in <a href="https://peps.python.org/pep-0646/">PEP 646 – Variadic Generics</a> are 
+ * TypeVarTuples and unpacked tuple types.
+ *
+ * @see PyTypeVarTupleType
+ * @see PyUnpackedTupleType
+ */
 @ApiStatus.Experimental
 public interface PyVariadicType extends PyType {
   @Override