From 3a00b3f612805ea8a3c1dabf2e30412a7a698d3c Mon Sep 17 00:00:00 2001
From: Katharine Hyatt <khyatt@flatironinstitute.org>
Date: Tue, 7 Aug 2018 16:56:52 -0400
Subject: [PATCH] Doc sorting algos

---
 base/sort.jl         | 60 ++++++++++++++++++++++++++++++++++++++++++++
 doc/src/base/sort.md | 12 ++++++---
 2 files changed, 68 insertions(+), 4 deletions(-)

diff --git a/base/sort.jl b/base/sort.jl
index c5cd7232e65c4..e04829a3191c4 100644
--- a/base/sort.jl
+++ b/base/sort.jl
@@ -370,6 +370,20 @@ struct InsertionSortAlg <: Algorithm end
 struct QuickSortAlg     <: Algorithm end
 struct MergeSortAlg     <: Algorithm end
 
+"""
+    PartialQuickSort{T <: Union{Int,OrdinalRange}}
+
+Indicate that a sorting function should use the partial quick sort
+algorithm. Partial quick sort returns the smallest `k` elements sorted from smallest
+to largest, finding them and sorting them using [`QuickSort`](@ref).
+
+Characteristics:
+  * *not stable*: does not preserve the ordering of elements which
+    compare equal (e.g. "a" and "A" in a sort of letters which
+    ignores case).
+  * *in-place* in memory.
+  * *divide-and-conquer*: sort strategy similar to [`MergeSort`](@ref).
+"""
 struct PartialQuickSort{T <: Union{Int,OrdinalRange}} <: Algorithm
     k::T
 end
@@ -379,8 +393,54 @@ Base.last(a::PartialQuickSort{Int}) = a.k
 Base.first(a::PartialQuickSort) = first(a.k)
 Base.last(a::PartialQuickSort) = last(a.k)
 
+"""
+    InsertionSort
+
+Indicate that a sorting function should use the insertion sort
+algorithm. Insertion sort traverses the collection one element
+at a time, inserting each element into its correct, sorted position in
+the output list.
+
+Characteristics:
+  * *stable*: preserves the ordering of elements which
+    compare equal (e.g. "a" and "A" in a sort of letters
+    which ignores case).
+  * *in-place* in memory.
+  * *quadratic performance* in the number of elements to be sorted:
+    it is well-suited to small collections but should not be used for large ones.
+"""
 const InsertionSort = InsertionSortAlg()
+"""
+    QuickSort
+
+Indicate that a sorting function should use the quick sort
+algorithm, which is *not* stable.
+
+Characteristics:
+  * *not stable*: does not preserve the ordering of elements which
+    compare equal (e.g. "a" and "A" in a sort of letters which
+    ignores case).
+  * *in-place* in memory.
+  * *divide-and-conquer*: sort strategy similar to [`MergeSort`](@ref).
+  * *good performance* for large collections.
+"""
 const QuickSort     = QuickSortAlg()
+"""
+    MergeSort
+
+Indicate that a sorting function should use the merge sort
+algorithm. Merge sort divides the collection into
+subcollections and repeatedly merges them, sorting each
+subcollection at each step, until the entire
+collection has been recombined in sorted form.
+
+Characteristics:
+  * *stable*: preserves the ordering of elements which compare
+    equal (e.g. "a" and "A" in a sort of letters which ignores
+    case).
+  * *not in-place* in memory.
+  * *divide-and-conquer* sort strategy.
+"""
 const MergeSort     = MergeSortAlg()
 
 const DEFAULT_UNSTABLE = QuickSort
diff --git a/doc/src/base/sort.md b/doc/src/base/sort.md
index a3c3b7c3df338..17a9b8c5ed97d 100644
--- a/doc/src/base/sort.md
+++ b/doc/src/base/sort.md
@@ -110,6 +110,10 @@ can be specified via the `lt` keyword.
 Base.sort!
 Base.sort
 Base.sortperm
+Base.InsertionSort
+Base.MergeSort
+Base.QuickSort
+Base.PartialQuickSort
 Base.Sort.sortperm!
 Base.Sort.sortslices
 ```
@@ -131,10 +135,10 @@ Base.Sort.partialsortperm!
 
 There are currently four sorting algorithms available in base Julia:
 
-  * `InsertionSort`
-  * `QuickSort`
-  * `PartialQuickSort(k)`
-  * `MergeSort`
+  * [`InsertionSort`](@ref)
+  * [`QuickSort`](@ref)
+  * [`PartialQuickSort(k)`](@ref)
+  * [`MergeSort`](@ref)
 
 `InsertionSort` is an O(n^2) stable sorting algorithm. It is efficient for very small `n`, and
 is used internally by `QuickSort`.