Added docstrings

Author: aleCombi

.gitignore

@@ -1 +1 @@
-/Manifest.toml
+**/Manifest.toml

src/pricing_methods/black_scholes.jl

@@ -1,29 +1,49 @@
+# Black-Scholes pricing function for European vanilla options
 
-"""Computes the price of a vanilla European call option using the Black-Scholes model.
+"""
+Computes the price of a vanilla European call or put option using the Black-Scholes model.
 
 # Arguments
-- `pricer::Pricer{VanillaCall, BlackScholesInputs, BlackScholesMethod}`: 
-  A `Pricer` configured for Black-Scholes pricing of a vanilla European call.
+- `payoff::VanillaOption{European}`: 
+  A European-style vanilla option, either a call or put.
+- `marketInputs::BlackScholesInputs`: 
+  The market inputs required for Black-Scholes pricing, including forward price, risk-free rate, and volatility.
+- `::BlackScholesMethod`: 
+  A placeholder argument to specify the Black-Scholes pricing method.
 
 # Returns
-- The computed Black-Scholes price of the option.
+- The discounted expected price of the option under the Black-Scholes model.
+
+# Formula
+The Black-Scholes price is computed using:
 
-The Black-Scholes formula used is:
 ```
-d1 = (log(S / K) + (r + 0.5 * σ^2) * T) / (σ * sqrt(T))
+d1 = (log(F / K) + 0.5 * σ^2 * T) / (σ * sqrt(T))
 d2 = d1 - σ * sqrt(T)
-price = S * Φ(d1) - K * exp(-r * T) * Φ(d2)
+price = exp(-r * T) * cp * (F * Φ(cp * d1) - K * Φ(cp * d2))
 ```
-where `Φ` is the CDF of the standard normal distribution.
+
+where:
+- `F` is the forward price of the underlying,
+- `K` is the strike price,
+- `σ` is the volatility,
+- `r` is the risk-free rate,
+- `T` is the time to expiry in years,
+- `cp` is +1 for calls and -1 for puts,
+- `Φ(x)` is the cumulative distribution function (CDF) of the standard normal distribution.
+
+# Notes
+- The time to expiry `T` is computed as the difference between the option's expiry date and the reference date, assuming a 365-day year.
+- The function supports both call and put options through the `cp` factor, ensuring a unified formula.
 """
 function compute_price(payoff::VanillaOption{European}, marketInputs::BlackScholesInputs, ::BlackScholesMethod)
-  F = marketInputs.forward
-  K = payoff.strike
-  r = marketInputs.rate
-  σ = marketInputs.sigma
-  cp = payoff.call_put()
-  T = Dates.value.(payoff.expiry .- marketInputs.referenceDate) ./ 365 # we might want to specify daycount conventions to ensure consistency
-  d1 = (log(F / K) + 0.5 * σ^2 * T) / (σ * sqrt(T))
-  d2 = d1 - σ * sqrt(T)
-  return exp(-r*T) * cp * (F * cdf(Normal(), cp * d1) - K * cdf(Normal(), cp * d2))
-end
+    F = marketInputs.forward
+    K = payoff.strike
+    r = marketInputs.rate
+    σ = marketInputs.sigma
+    cp = payoff.call_put()
+    T = Dates.value.(payoff.expiry .- marketInputs.referenceDate) ./ 365  # Assuming 365-day convention
+    d1 = (log(F / K) + 0.5 * σ^2 * T) / (σ * sqrt(T))
+    d2 = d1 - σ * sqrt(T)
+    return exp(-r*T) * cp * (F * cdf(Normal(), cp * d1) - K * cdf(Normal(), cp * d2))
+end

src/pricing_methods/cox_ross_rubinstein.jl

@@ -1,40 +1,128 @@
-"""The Cox-Ross-Rubinstein binomial tree pricing method.
+# Cox-Ross-Rubinstein Binomial Tree Pricing Implementation
 
-This struct represents the Cox-Ross-Rubinstein binomial pricing model for option pricing.
+"""
+The Cox-Ross-Rubinstein binomial tree pricing method.
+
+This struct represents the Cox-Ross-Rubinstein (CRR) binomial pricing model for option pricing.
+
+# Fields
+- `steps`: The number of time steps in the binomial tree.
+
+# Notes
+- This implementation supports options written on either the **forward price** or the **spot price**.
+- When pricing an option on the forward price, discounting is already embedded in the forward.
+- When pricing an option on the spot price, discounting must be explicitly applied at each step.
+- The up probability is defined as:
+
+```
+p = 1 / (1 + u)
+```
+where:
+- `u = exp(σ√ΔT)` is the up-move factor,
+- `ΔT` is the time step duration in years.
 """
 struct CoxRossRubinsteinMethod <: AbstractPricingMethod 
-  steps
+    steps::Int
 end
 
-function binomial_tree_value(step, discounted_continuation, underlying_at_i, payoff, ::European)
-  return discounted_continuation
+"""
+Returns the value at a given node in the binomial tree for a European option.
+
+# Arguments
+- `discounted_continuation`: Discounted expected future values from the next step.
+- `::European`: Marker type for European exercise style.
+
+# Returns
+- The continuation value, as European options do not allow early exercise.
+"""
+function binomial_tree_value(_, discounted_continuation, _, _, ::European)
+    return discounted_continuation
 end
 
+"""
+Returns the value at a given node in the binomial tree for an American option.
+
+# Arguments
+- `step`: Current time step in the binomial tree.
+- `discounted_continuation`: Discounted expected future values from the next step.
+- `underlying_at_i`: Function to compute the underlying price at a given step.
+- `payoff`: Payoff function of the option.
+- `::American`: Marker type for American exercise style.
+
+# Returns
+- The maximum between the continuation value and the intrinsic value of the option (early exercise is considered).
+"""
 function binomial_tree_value(step, discounted_continuation, underlying_at_i, payoff, ::American)
-  return max.(discounted_continuation, payoff(underlying_at_i(step)))
+    return max.(discounted_continuation, payoff(underlying_at_i(step)))
 end
 
+"""
+Computes the underlying asset price at a given step when pricing an option on the **spot price**.
+
+# Arguments
+- `time_step`: Current time step in the binomial tree.
+- `forward`: Forward price of the underlying asset.
+- `rate`: Risk-free rate.
+- `delta_time`: Time step size in years.
+- `::Spot`: Marker type indicating the option is written on the spot price.
+
+# Returns
+- The estimated spot price, derived by discounting the forward price.
+"""
 function binomial_tree_underlying(time_step, forward, rate, delta_time, ::Spot)
-  return exp(-rate*time_step*delta_time) * forward
+    return exp(-rate * time_step * delta_time) * forward
 end
 
+"""
+Computes the underlying asset price at a given step when pricing an option on the **forward price**.
+
+# Arguments
+- `forward`: Forward price of the underlying asset.
+- `::Forward`: Marker type indicating the option is written on the forward price.
+
+# Returns
+- The forward price (unchanged, as forward prices already embed discounting).
+"""
 function binomial_tree_underlying(_, forward, _, _, ::Forward)
-  return forward
+    return forward
 end
 
-function compute_price(payoff::P, market_inputs::BlackScholesInputs, method::CoxRossRubinsteinMethod) where P <: AbstractPayoff
-  ΔT = Dates.value.(payoff.expiry .- market_inputs.referenceDate) ./ 365 / method.steps # we might want to specify daycount conventions to ensure consistency
-  up_step = exp(market_inputs.sigma * sqrt(ΔT))
-  forward_at_i(i) = market_inputs.forward * up_step .^ (-i:2:i)
-  underlying_at_i(i) = binomial_tree_underlying(i, forward_at_i(i), market_inputs.rate, ΔT, payoff.underlying)
-  up_probability = 1 / (1 + up_step)
-  value = payoff(forward_at_i(method.steps))
-
-  for step in (method.steps-1):-1:0
-    continuation = up_probability * value[2:end] + (1 - up_probability) * value[1:end-1]
-    df = exp(-market_inputs.rate * ΔT)
-    value = binomial_tree_value(step, df * continuation, underlying_at_i, payoff, payoff.exercise_style)
-  end
-
-  return value[1]
-end
+"""
+Computes the price of a vanilla option using the Cox-Ross-Rubinstein binomial tree model.
+
+# Arguments
+- `payoff`: The option payoff function, which determines intrinsic value.
+- `market_inputs`: Market data including forward price, risk-free rate, and volatility.
+- `method`: The CRR pricing method with a defined number of steps.
+
+# Returns
+- The computed option price using backward induction.
+
+# Notes
+- This implementation supports **options on either forward prices or spot prices**.
+  - If the option is written on a forward price, discounting is embedded.
+  - If the option is written on a spot price, discounting is applied explicitly.
+- The up-move factor is computed as `u = exp(σ√ΔT)`, and the up probability is given by `p = 1 / (1 + u)`.
+"""
+function compute_price(payoff, market_inputs, method::CoxRossRubinsteinMethod)
+    steps = method.steps
+    ΔT = Dates.value.(payoff.expiry - market_inputs.referenceDate) / 365 / steps  # Assuming ACT/365 day count
+    u = exp(market_inputs.sigma * sqrt(ΔT))  # Up-move factor
+    forward_at_i(i) = market_inputs.forward * u .^ (-i:2:i)
+    underlying_at_i(i) = binomial_tree_underlying(i, forward_at_i(i), market_inputs.rate, ΔT, payoff.underlying)
+
+    # Up probability in forward measure
+    p = 1 / (1 + u)
+
+    # Initialize terminal payoffs
+    value = payoff.(forward_at_i(steps))
+
+    # Backward induction
+    for step in (steps-1):-1:0
+        continuation = p * value[2:end] + (1 - p) * value[1:end-1]
+        df = exp(-market_inputs.rate * ΔT)  # Discounting
+        value = binomial_tree_value(step, df * continuation, underlying_at_i, payoff, payoff.exercise_style)
+    end
+
+    return value[1]
+end

src/pricing_methods/pricing_methods.jl

@@ -1,27 +1,34 @@
+# Exported Types and Functions
 export AbstractPricingMethod, BlackScholesMethod, Pricer, compute_price, CoxRossRubinsteinMethod
 
-"""An abstract type representing a pricing method."""
+"""
+An abstract type representing a pricing method.
+
+All pricing methods, such as Black-Scholes or binomial trees, should inherit from this type.
+"""
 abstract type AbstractPricingMethod end
 
-"""The Black-Scholes pricing method.
+"""
+The Black-Scholes pricing method.
 
-This struct represents the Black-Scholes pricing model for option pricing.
+This struct represents the Black-Scholes pricing model for option pricing, which assumes a lognormal distribution for the underlying asset and continuous hedging.
 """
 struct BlackScholesMethod <: AbstractPricingMethod end
 
-"""A pricer that calculates the price of a derivative using a given payoff, market data, and a pricing model.
+"""
+A pricer that calculates the price of a derivative using a given payoff, market data, and a pricing model.
 
 # Type Parameters
-- `P <: AbstractPayoff`: The type of payoff being priced.
-- `M <: AbstractMarketInputs`: The type of market data inputs required for pricing.
-- `S <: AbstractPricingMethod`: The pricing method used.
+- `P`: The type of payoff being priced (must be a subtype of `AbstractPayoff`).
+- `M`: The type of market data inputs required for pricing (must be a subtype of `AbstractMarketInputs`).
+- `S`: The pricing method used (must be a subtype of `AbstractPricingMethod`).
 
 # Fields
-- `marketInputs::M`: The market data inputs used for pricing.
-- `payoff::P`: The derivative payoff.
-- `pricingMethod::S`: The pricing model used for valuation.
+- `payoff`: The derivative payoff.
+- `marketInputs`: The market data inputs used for pricing.
+- `pricingMethod`: The pricing model used for valuation.
 
-A `Pricer` is a callable struct that computes the price of the derivative using the specified pricing method.
+A `Pricer` is a callable struct that computes the price of the derivative using the specified pricing method when invoked.
 """
 struct Pricer{P <: AbstractPayoff, M <: AbstractMarketInputs, S <: AbstractPricingMethod}
   payoff::P  
@@ -30,16 +37,16 @@ struct Pricer{P <: AbstractPayoff, M <: AbstractMarketInputs, S <: AbstractPrici
 end
 
 """
-  Computes the price based on a Pricer input object.
+Computes the price of a derivative using a `Pricer` object.
 
-  # Arguments
-- `pricer::Pricer{A, B, C}`: 
-  A `Pricer`, specifying a payoff, a market inputs and a method.
+# Arguments
+- `pricer`: A `Pricer` containing the payoff, market inputs, and pricing method.
 
 # Returns
-- The computed price of the derivative.
+- The computed price of the derivative based on the specified pricing model.
 
+This function allows a `Pricer` instance to be called directly as a function, forwarding the computation to `compute_price`.
 """
 function (pricer::Pricer{A,B,C})() where {A<:AbstractPayoff,B<:AbstractMarketInputs,C<:AbstractPricingMethod}
   return compute_price(pricer.payoff, pricer.marketInputs, pricer.pricingMethod)
-end
+end