DOCS: Comprehensive documentation review and improvements with reduced maintenance costs (#789)

* Initial plan

* Fix major docstring issues in distributions, markov core, and utility functions

Co-authored-by: mmcky <8263752+mmcky@users.noreply.github.com>

* Complete documentation review with additional docstring fixes and coverage analysis

Co-authored-by: mmcky <8263752+mmcky@users.noreply.github.com>

* Remove redundant property docstrings to reduce maintenance costs

Co-authored-by: mmcky <8263752+mmcky@users.noreply.github.com>

* Remove redundant docstrings to reduce maintenance costs as requested

Co-authored-by: mmcky <8263752+mmcky@users.noreply.github.com>

---------

Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: mmcky <8263752+mmcky@users.noreply.github.com>

Author: Copilot

quantecon/distributions.py

@@ -28,6 +28,14 @@ class BetaBinomial:
     Attributes
     ----------
     n, a, b : see Parameters
+    mean : float
+        Mean of the Beta-binomial distribution, equal to n * a / (a + b).
+    std : float
+        Standard deviation of the Beta-binomial distribution.
+    var : float
+        Variance of the Beta-binomial distribution.
+    skew : float
+        Skewness of the Beta-binomial distribution.
 
     """
 
@@ -36,26 +44,22 @@ def __init__(self, n, a, b):
 
     @property
     def mean(self):
-        "mean"
         n, a, b = self.n, self.a, self.b
         return n * a / (a + b)
 
     @property
     def std(self):
-        "standard deviation"
         return sqrt(self.var)
 
     @property
     def var(self):
-        "Variance"
         n, a, b = self.n, self.a, self.b
         top = n*a*b * (a + b + n)
         btm = (a+b)**2.0 * (a+b+1.0)
         return top / btm
 
     @property
     def skew(self):
-        "skewness"
         n, a, b = self.n, self.a, self.b
         t1 = (a+b+2*n) * (b - a) / (a+b+2)
         t2 = sqrt((1+a+b) / (n*a*b * (n+a+b)))

quantecon/game_theory/brd.py

@@ -165,7 +165,6 @@ def __init__(self, payoff_matrix, N, epsilon=0.1):
     def play(self, action, action_dist, **options):
         """
         See `play` in `BRD`.
-
         """
         tie_breaking = options.get('tie_breaking', self.tie_breaking)
         tol = options.get('tol', None)
@@ -224,7 +223,6 @@ def __init__(self, payoff_matrix, N, k=2):
     def play(self, action, action_dist, **options):
         """
         See `play` in `BRD`.
-
         """
         tie_breaking = options.get('tie_breaking', self.tie_breaking)
         tol = options.get('tol', None)

quantecon/game_theory/game_converters.py

@@ -32,6 +32,19 @@
 
 
 def str2num(s):
+    """
+    Convert string to appropriate numeric type.
+    
+    Parameters
+    ----------
+    s : str
+        String representation of a number.
+    
+    Returns
+    -------
+    int or float
+        Integer if no decimal point, otherwise float.
+    """
     if '.' in s:
         return float(s)
     return int(s)

quantecon/game_theory/normal_form_game.py

@@ -562,6 +562,10 @@ class NormalFormGame:
     payoff_arrays : tuple(ndarray(float, ndim=N))
         Tuple of the payoff arrays, one for each player.
 
+    payoff_profile_array : ndarray(float, ndim=N+1)
+        Array of shape (n_0, ..., n_{N-1}, N) containing the payoff
+        profiles, where the last axis represents the players.
+
     """
     def __init__(self, data, dtype=None):
         # data represents an array_like of Players

quantecon/game_theory/repeated_game.py

@@ -61,6 +61,11 @@ def equilibrium_payoffs(self, method=None, options=None):
                     Maximum number of iterations.
                 u_init : ndarray(float, ndim=1)
                     The initial guess of threat points.
+        
+        Returns
+        -------
+        ndarray(float, ndim=2)
+            Array containing the set of equilibrium payoff pairs.
 
         Notes
         -----

quantecon/markov/approximation.py

@@ -115,9 +115,24 @@ def rouwenhorst(n, rho, sigma, mu=0.):
 
     def row_build_mat(n, p, q):
         """
+        Build the transition matrix for the Rouwenhorst method.
+        
         This method uses the values of p and q to build the transition
-        matrix for the rouwenhorst method
-
+        matrix for the rouwenhorst method.
+        
+        Parameters
+        ----------
+        n : int
+            The size of the transition matrix (number of states).
+        p : float
+            First probability parameter.
+        q : float 
+            Second probability parameter.
+            
+        Returns
+        -------
+        ndarray(float, ndim=2)
+            The n x n transition matrix.
         """
 
         if n == 2:
@@ -232,6 +247,19 @@ def tauchen(n, rho, sigma, mu=0., n_std=3):
 
 @njit
 def std_norm_cdf(x):
+    """
+    Standard normal cumulative distribution function.
+    
+    Parameters
+    ----------
+    x : float
+        Input value.
+        
+    Returns
+    -------
+    float
+        CDF value at x for standard normal distribution.
+    """
     return 0.5 * erfc(-x / sqrt(2))
 
 

quantecon/markov/core.py

@@ -112,6 +112,13 @@ class MarkovChain:
     P : ndarray or scipy.sparse.csr_matrix (float, ndim=2)
         See Parameters
 
+    state_values : array_like or None
+        Array of state values if set, None otherwise.
+
+    digraph : DiGraph
+        Directed graph representation of the Markov chain with nodes as 
+        states and edges as positive transition probabilities.
+
     stationary_distributions : array_like(float, ndim=2)
         Array containing stationary distributions, one for each
         recurrent class, as rows.
@@ -224,6 +231,14 @@ def state_values(self):
 
     @state_values.setter
     def state_values(self, values):
+        """
+        Set state values of the MarkovChain.
+        
+        Parameters
+        ----------
+        values : array_like or None
+            Array of state values with length n, or None to unset.
+        """
         if values is None:
             self._state_values = None
         else:

quantecon/markov/gth_solve.py

@@ -36,15 +36,18 @@ def gth_solve(A, overwrite=False, use_jit=True):
     ----------
     A : array_like(float, ndim=2)
         Stochastic matrix or generator matrix. Must be of shape n x n.
+    
+    overwrite : bool, optional(default=False)
+        Whether to overwrite `A`.
+    
+    use_jit : bool, optional(default=True)
+        Whether to use JIT compilation for performance.
 
     Returns
     -------
     x : numpy.ndarray(float, ndim=1)
         Stationary distribution of `A`.
 
-    overwrite : bool, optional(default=False)
-        Whether to overwrite `A`.
-
     References
     ----------
     .. [1] W. K. Grassmann, M. I. Taksar and D. P. Heyman, "Regenerative

quantecon/quad.py

@@ -24,11 +24,37 @@
 
 @vectorize(nopython=True)
 def gammaln(x):
+    """
+    Natural logarithm of the gamma function.
+    
+    Parameters
+    ----------
+    x : float
+        Input value.
+        
+    Returns
+    -------
+    float
+        Natural logarithm of gamma(x).
+    """
     return math.lgamma(x)
 
 
 @vectorize(nopython=True)
 def fix(x):
+    """
+    Round towards zero.
+    
+    Parameters
+    ----------
+    x : float
+        Input value.
+        
+    Returns
+    -------
+    float
+        Rounded value towards zero.
+    """
     if x < 0:
         return math.ceil(x)
     else:
@@ -242,6 +268,9 @@ def qnwnorm(n, mu=None, sig2=None, usesqrtm=False):
     sig2 : array_like(float), optional(default=eye(d))
         A d x d array representing the variance-covariance matrix of the
         multivariate normal distribution.
+    
+    usesqrtm : bool, optional(default=False)
+        Whether to use matrix square root method for decomposition.
 
     Returns
     -------

quantecon/util/timing.py

@@ -29,7 +29,11 @@ class __Timer__:
     def tic(self):
         """
         Save time for future use with `tac()` or `toc()`.
-
+        
+        Returns
+        -------
+        None
+            This function doesn't return a value.
         """
         t = time.time()
         self.start = t