From 0977632eab18be71e3027846d39972a70e815115 Mon Sep 17 00:00:00 2001
From: Malte Londschien <malte@londschien.de>
Date: Fri, 27 Oct 2023 12:28:27 +0200
Subject: [PATCH] Improve some docstrings.

---
 ivmodels/kclass.py | 33 +++++++++++++++++++--------------
 1 file changed, 19 insertions(+), 14 deletions(-)

diff --git a/ivmodels/kclass.py b/ivmodels/kclass.py
index 147f24a..c8134f0 100644
--- a/ivmodels/kclass.py
+++ b/ivmodels/kclass.py
@@ -136,23 +136,23 @@ def _X_Z(self, X, Z=None, check=True):
 
     def _fuller_alpha(self, kappa):
         """
-        Extract the alpha parameter from the kappa parameter.
+        Extract the Fuller alpha parameter from the kappa parameter.
 
         Parameters
         ----------
-        kappa: float or str
-            The kappa parameter. Must be a float, 'fuller(a)' for some integer or float
-            a, 'fuller', or 'liml'.
+        kappa: str
+            The kappa parameter. Must be ``"fuller(a)"`` for some integer or float
+            ``a``, ``"fuller"``, or ``"liml"``.
 
         Returns
         -------
         fuller_alpha: float
-            The alpha parameter. If kappa is a float, then alpha = kappa. If kappa is
-            'fuller(a)' for some integer or float a, then alpha = a. If kappa is
-            'fuller', then alpha = 1. If kappa is 'liml', then alpha = 0.
+            The alpha parameter. If kappa is ``"fuller(a)"`` for some integer or float
+            ``a``, then ``alpha = a``. If kappa is ``"fuller"``, then ``alpha = 1``.
+            If kappa is ``"liml"``, then ``alpha = 0``.
         """
         if not isinstance(kappa, str):
-            return float(kappa)
+            raise ValueError(f"Invalid kappa {kappa}. Must be a string.")
 
         fuller_match = re.match(r"fuller(\(\d+\.?\d*\))?", kappa, re.IGNORECASE)
         liml_match = re.match("liml", kappa, re.IGNORECASE)
@@ -197,7 +197,8 @@ def _kappa_liml(self, X, y, Z=None, X_proj=None, y_proj=None):
         Returns
         -------
         kappa_liml: float
-            Smallest eigenvalue of ``((X y)^T (X y))^{-1} (X y)^T P_Z (X y)``, where
+            One plus the smallest eigenvalue of
+            ``((X y)^T M_Z (X y))^{-1} (X y)^T P_Z (X y)``, where
             ``P_Z`` is the projection matrix onto the subspace spanned by Z.
         """
         if X_proj is None:
@@ -321,17 +322,21 @@ class KClass(KClassMixin, GeneralizedLinearRegressor):
 
     Parameters
     ----------
-    kappa: float or {fuller(a), liml}
+    kappa: float or {"fuller(a)", "liml", "ols", "tsls", "2sls"}
         The kappa parameter of the k-class estimator. If float, then kappa must be in
         :math:`[0, \\hat\\kappa_\\mathrm{LIML}]]`, where
         :math:`\\kappa_\\mathrm{LIML} \\geq 1` is 1 plus the smallest eigenvalue of the
         matrix :math:`((X \\ \\ y)^T M_Z (X \\ \\ y))^{-1} (X \\ \\ y)^T P_Z (X \\ y)`.
         and :math:`P_Z` is the projection matrix onto the subspace spanned by :math:`Z`
         and :math:`M_Z = Id - P_Z`.
-        If string, then must be one of ``"liml"``, ``"fuller"``, or ``"fuller(a)"``,
-        where ``a`` is numeric. If ``kappa="liml"``, then
-        :math:`\\kappa = \\hat\\kappa_\\mathrm{LIML}` is used. If ``kappa="fuller(a)"``,
-        then :math:`\\kappa = \\hat\\kappa_\\mathrm{LIML} - a / (n - q)`, where
+        If string, then must be one of ``"liml"``, ``"ols"``, ``"2sls"``, ``"tsls"``,
+        ``"fuller"``, or ``"fuller(a)"``, where ``a`` is numeric. If ``kappa="ols"``,
+        then ``kappa=0`` and the k-class estimator is the ordinary least squares
+        estimator. If ``kappa="tsls"`` or ``kappa="2sls"``m then ``kappa=1`` and the
+        k-class estimator is the two-stage least-squares estimator. If ``kappa="liml"``,
+        then :math:`\\kappa = \\hat\\kappa_\\mathrm{LIML}` is used. If
+        ``kappa="fuller(a)"``, then
+        :math:`\\kappa = \\hat\\kappa_\\mathrm{LIML} - a / (n - q)`, where
         :math:`n` is the number of observations and :math:`q = \\mathrm{dim}(Z)` is the
         number of instruments. The string ``"fuller"`` is interpreted as
         ``"fuller(1.0)"``, yielding an estimator that is unbiased up to