From 887f9d7e34610c7e13bf055b201596aaf0827dcc Mon Sep 17 00:00:00 2001
From: "mhsatman@gmail.com" <mhsatman@gmail.com>
Date: Fri, 2 Aug 2024 21:25:02 +0300
Subject: [PATCH] add documentation for traveling salesman

---
 docs/src/algorithms.md   |  6 +++++
 src/travelingsalesman.jl | 52 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)

diff --git a/docs/src/algorithms.md b/docs/src/algorithms.md
index 2ac6011..ede32d8 100644
--- a/docs/src/algorithms.md
+++ b/docs/src/algorithms.md
@@ -75,3 +75,9 @@ OperationsResearchModels.johnsons_ga
 ```@docs
 OperationsResearchModels.makespan
 ```
+
+
+## Traveling Salesman
+```@docs
+OperationsResearchModels.travelingsalesman
+```
\ No newline at end of file
diff --git a/src/travelingsalesman.jl b/src/travelingsalesman.jl
index 91823a1..463c276 100644
--- a/src/travelingsalesman.jl
+++ b/src/travelingsalesman.jl
@@ -10,6 +10,58 @@ struct TravelinSalesmenResult
     cost::Float64
 end
 
+
+
+"""
+    travelingsalesman(distancematrix::Matrix; popsize = 100, ngen = 1000, pcross = 0.8, pmutate = 0.01, nelites = 1)::TravelinSalesmenResult
+
+Given a matrix of distances, returns a TravelinSalesmenResult with the best route and its cost.
+
+# Arguments
+
+- `distancematrix::Matrix`: a matrix of distances
+- `popsize::Int`: the population size. Default is 100
+- `ngen::Int`: the number of generations. Default is 1000
+- `pcross::Float64`: the crossover probability. Default is 0.8
+- `pmutate::Float64`: the mutation probability. Default is 0.01
+- `nelites::Int`: the number of elites. Default is 1
+
+# Returns
+
+- `TravelinSalesmenResult`: a custom data type that holds the best route and its cost
+
+# Example
+
+```julia
+pts = Float64[
+    0 0;
+    0 1;
+    0 2;
+    1 2;
+    2 2;
+    3 2;
+    4 2; 
+    5 2;
+    5 1;
+    5 0;
+    4 0;
+    3 0;
+    2 0;
+    1 0;
+]
+
+n = size(pts, 1
+distmat = zeros(n, n)
+
+for i in 1:n
+    for j in 1:n
+        distmat[i, j] = sqrt(sum((pts[i, :] .- pts[j, :]).^2))
+    end 
+end
+
+result = travelingsalesman(distmat, ngen = 1000, popsize = 100, pcross = 1.0, pmutate = 0.10)
+```
+"""
 function travelingsalesman(distancematrix::Matrix{TType}; 
     popsize = 100, ngen = 1000, pcross = 0.8, pmutate = 0.01, nelites = 1):: TravelinSalesmenResult where {TType<:Float64}