updated docs for EF

pypfopt/objective_functions.py

@@ -1,16 +1,19 @@
-""" Objective functions for optimisation methods
+"""
+The ``objective_functions`` module provides optimisation objectives, including the actual
+objective functions called by the ``EfficientFrontier`` object's optimisation methods.
+These methods are primarily designed for internal use during optimisation (via
+scipy.optimize), and each requires a certain signature (which is why they have not been
+factored into a class). For obvious reasons, any objective function must accept ``weights``
+as an argument, and must also have at least one of ``expected_returns`` or ``cov_matrix``.
 
-Implements the actual objective functions called by the EfficientFrontier object's
-optimisation methods. These methods are primarily designed for internal use during optimisation
-(via scipy.optimize), and require a certain signature (which is why they have not been factored into
-a class).
-
-Because scipy.optimize only minimises, any objectives that we want to maximise must be made negative.
+Because scipy.optimize only minimises, any objectives that we want to maximise must be
+made negative.
 
 Currently implemented:
+
 - negative mean return
-- negative Sharpe ratio
-- volatility
+- (regularised) negative Sharpe ratio
+- (regularised) volatility
 """
 
 import numpy as np
@@ -44,7 +47,7 @@ def negative_sharpe(
     :type cov_matrix: pd.DataFrame
     :param gamma: L2 regularisation parameter, defaults to 0. Increase if you want more
                     non-negligible weights
-    :param gamma: float, optional
+    :type gamma: float, optional
     :param risk_free_rate: risk free rate of borrowing/lending, defaults to 0.02
     :type risk_free_rate: float, optional
     :return: negative Sharpe ratio
@@ -59,10 +62,14 @@ def negative_sharpe(
 def volatility(weights, cov_matrix, gamma=0):
     """
     Calculate the volatility of a portfolio
+
     :param weights: asset weights of the portfolio
     :type weights: np.ndarray
     :param cov_matrix: the covariance matrix of asset returns
     :type cov_matrix: pd.DataFrame
+    :param gamma: L2 regularisation parameter, defaults to 0. Increase if you want more
+                  non-negligible weights
+    :type gamma: float, optional
     :return: portfolio volatility
     :rtype: float
     """