Separate documentation for different similarities and related hash functions into their own pages. Improve documentation across the board for various functions and LSHFunction subtypes. In addition, add DEFAULT_* constants to define default values of common arguments used by LSHFunction subtypes. Finally, add utilities to LSHBase.jl that generate docstrings for common arguments and keyword parameters.

Squashed commit of the following:

commit cdaacc5
Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com>
Date:   Fri Jan 17 16:03:11 2020 -0700

    Remove old MIPSHash documentation.

commit 64596cd
Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com>
Date:   Fri Jan 17 16:00:48 2020 -0700

    Fix SignALSH docs. Add improved documentation for MIPSHash, and fix an issue where MIPSHash doesn't raise an error when the input exceeds maxnorm.

commit 0e5f506
Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com>
Date:   Fri Jan 17 15:34:03 2020 -0700

    Add improved documentation for SignALSH.

commit 653c5cc
Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com>
Date:   Fri Jan 17 15:13:24 2020 -0700

    Ensure that only documentation for inner_prod(::AbstractVector, ::AbstractVector) is shown on the page for inner product similarity.

commit a2caca8
Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com>
Date:   Fri Jan 17 15:11:55 2020 -0700

    Add DEFAULT_* arguments to specify default values for common keyword arguments used in the LSH module. Add some functions to automatically generate docstrings for those arguments.

commit 8954625
Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com>
Date:   Fri Jan 17 14:32:05 2020 -0700

    Add missing docstring for SimHash.

commit 5c575e9
Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com>
Date:   Fri Jan 17 14:22:28 2020 -0700

    Reformat reference cited in MinHash documentation.

commit 2f8c9ef
Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com>
Date:   Fri Jan 17 14:21:21 2020 -0700

    Fix some docstrings for l^p / L^p distance.

commit 003ed87
Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com>
Date:   Fri Jan 17 14:01:11 2020 -0700

    Add some refs for l^p and L^p distances in similarities.jl.

commit a528d43
Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com>
Date:   Fri Jan 17 13:49:16 2020 -0700

    Generate docs for L1Hash and L2Hash.

commit 6f261a9
Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com>
Date:   Fri Jan 17 13:19:38 2020 -0700

    Use names of hash functions (instead of just a section titled 'Hash Functions') on the pages for each similarity function.

commit 7d4cf5f
Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com>
Date:   Fri Jan 17 13:10:51 2020 -0700

    Separate similarity functions so that they have their own pages.

commit 277ed49
Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com>
Date:   Fri Jan 17 13:01:15 2020 -0700

    Remove information about other similarity search techniques from the landing page of the docs.

Author: kernelmethod

docs/make.jl

@@ -12,7 +12,12 @@ makedocs(
     format   = Documenter.HTML(),
     modules  = [LSH],
     pages    = ["Home" => "index.md",
-                "Similarity functions" => "similarities.md"]
+                "Similarity functions" => [
+                    "Cosine similarity" => joinpath("similarities", "cosine.md"),
+                    raw"``\ell^p`` distance" => joinpath("similarities", "lp_distance.md"),
+                    "Jaccard similarity" => joinpath("similarities", "jaccard.md"),
+                    "Inner product similarity" => joinpath("similarities", "inner_prod.md")]
+               ]
 )
 
 deploydocs(

docs/src/index.md

@@ -16,12 +16,6 @@ Broadly, there are two computational issues with this approach:
 - First, the database may be massive, much larger than could possibly fit in memory. This would make the brute-force approach of computing ``s(x,y)`` for every point ``y`` in the database far too expensive to be practical.
 - Second, the dimensionality of the data may be such that computing ``s(x,y)`` is itself expensive. In addition, the similarity function itself may simply be intrinsically difficult to compute. For instance, calculating Wasserstein distance entails solving a very high-dimensional linear program.
 
-In order to solve these problems, researchers have over time developed a variety of techniques to accelerate similarity search:
-
-- [``k``-d trees](https://en.wikipedia.org/wiki/K-d_tree)
-- [Ball trees](https://en.wikipedia.org/wiki/Ball_tree)
-- Data reduction techniques
-
 ## Locality-sensitive hashing
 *Locality-sensitive hashing* (LSH) is a technique for accelerating similarity search that works by using a hash function on the query point ``x`` and limiting similarity search to only those points in the database that experience a hash collision with ``x``. The hash functions that are used are randomly generated from a family of *locality-sensitive hash functions*. These hash functions have the property that ``Pr[h(x) = h(y)]`` (i.e., the probability of a hash collision) increases the more similar that ``x`` and ``y`` are.
 
@@ -34,5 +28,7 @@ LSH.jl is a package that provides definitions of locality-sensitive hash functio
 - Inner product (`inner_prod`)
 - Function-space hashes (`L1`, `L2`, and `cossim`)
 
+## Contents
+
 ```@contents
 ```

docs/src/similarities.md

@@ -0,0 +1,13 @@
+# Cosine similarity
+
+## SimHash
+
+```@docs
+SimHash
+```
+
+## Utilities
+
+```@docs
+cossim
+```

docs/src/similarities/cosine.md

@@ -0,0 +1,19 @@
+# Inner product similarity
+
+## SignALSH
+
+```@docs
+SignALSH
+```
+
+## MIPSHash
+
+```@docs
+MIPSHash
+```
+
+## Utilities
+
+```@docs
+inner_prod(::AbstractVector, ::AbstractVector)
+```

docs/src/similarities/inner_prod.md

@@ -0,0 +1,13 @@
+# Jaccard similarity
+
+## MinHash
+
+```@docs
+MinHash
+```
+
+## Utilities
+
+```@docs
+jaccard
+```

docs/src/similarities/jaccard.md

@@ -0,0 +1,17 @@
+# ``\ell^p`` distance
+
+## L1Hash and L2Hash
+
+```@docs
+L1Hash
+L2Hash
+```
+
+## Utility functions
+
+```@docs
+ℓp
+ℓp_norm
+Lp(::AbstractVector{T}, ::AbstractVector, ::Real) where T
+Lp_norm(::AbstractVector, ::Real)
+```

docs/src/similarities/lp_distance.md

@@ -12,7 +12,10 @@ Global variables and constants
 # been associated with hash functions via the register_similarity! macro.
 const available_similarities = Set()
 
-available_similarities_as_strings() = available_similarities .|> string |> sort
+# Defaults to use for common arguments
+const DEFAULT_N_HASHES = 1
+const DEFAULT_DTYPE = Float32
+const DEFAULT_RESIZE_POW2 = false
 
 #========================
 Abstract typedefs
@@ -64,3 +67,20 @@ The following functions must be defined for all AsymmetricLSHFunction subtypes
 =#
 function index_hash end
 function query_hash end
+
+#========================
+Documentation utilities
+========================#
+
+available_similarities_as_strings() = available_similarities .|> string |> sort
+
+### Docstring generators for common keyword arguments
+N_HASHES_DOCSTR(; default = DEFAULT_N_HASHES) = """
+`n_hashes::Integer` (default: `$(default)`): the number of hash functions to generate."""
+
+DTYPE_DOCSTR(hashfn; default = DEFAULT_DTYPE) = """
+`dtype::DataType` (default: `$(default)`): the data type to use in the $(hashfn) internals. For performance reasons you should pick `dtype` to match the type of the data you're hashing."""
+
+RESIZE_POW2_DOCSTR(hashfn; default = DEFAULT_RESIZE_POW2) = """
+`resize_pow2::Bool` (default: `$(default)`): affects the way in which the returned `$(hashfn)` resizes to hash inputs of different sizes. If you think you'll be hashing inputs of many different sizes, it's more efficient to set `resize_pow2 = true`."""
+

src/LSHBase.jl

@@ -52,10 +52,10 @@ end
 
 ### External LpHash constructors
 
-function LpHash{T}(n_hashes::Integer = 1;
+function LpHash{T}(n_hashes::Integer = DEFAULT_N_HASHES;
                    r::Real = T(1.0),
                    power::Integer = 2,
-                   resize_pow2::Bool = false) where {T <: Union{Float32,Float64}}
+                   resize_pow2::Bool = DEFAULT_RESIZE_POW2) where {T <: Union{Float32,Float64}}
 
     coeff = Matrix{T}(undef, n_hashes, 0)
     shift = rand(T, n_hashes)
@@ -77,53 +77,53 @@ L1Hash(args...; kws...) where {T} = LpHash(args...; power = 1, kws...)
 
 L2Hash(args...; kws...) where {T} = LpHash(args...; power = 2, kws...)
 
-LpHash(args...; dtype::DataType = Float32, kws...) =
+LpHash(args...; dtype::DataType = DEFAULT_DTYPE, kws...) =
     LpHash{dtype}(args...; kws...)
 
-# Documentation for L1Hash and L2Hash
-@doc raw"""
-    L1Hash(n_hashes::Integer = 1;
-           dtype::DataType = Float32,
-           r::Real = 1.0,
-           resize_pow2::Bool = false)
-    L2Hash(n_hashes::Integer = 1;
-           dtype::DataType = Float32,
-           r::Real = 1.0,
-           resize_pow2::Bool = false)
+### Documentation for L1Hash and L2Hash
+for (hashfn, power) in zip((:L1Hash, :L2Hash), (1, 2))
+    sim = "ℓ$(power)"
+    equation = (power == 1) ?
+                "\\|x - y\\|_$(power) = \\sum_i |x_i - y_i|" :
+                "\\|x - y\\|_$(power) = \\left(\\sum_i |x_i - y_i|^$(power)\\right)^{1/$(power)}"
 
-Constructs a locality-sensitive hash for ``\ell^p`` distance (``\|x - y\|_p``). `L1Hash` constructs a hash function for ``\ell^1`` distance, and `L2Hash` constructs a hash function for ``\ell^2`` distance.
+    quote
+@doc """
+    $($hashfn)(
+        n_hashes::Integer = $(DEFAULT_N_HASHES);
+        dtype::DataType = $(DEFAULT_DTYPE),
+        r::Real = 1.0,
+        resize_pow2::Bool = $(DEFAULT_RESIZE_POW2)
+    )
+
+Constructs a locality-sensitive hash for ``\\ell^$($power)`` distance (``\\|x - y\\|_$($power)``), defined as
+
+``$($equation)``
 
 # Arguments
-- `n_hashes::Integer` (default: `1`): the number of hash functions to generate.
+- $(N_HASHES_DOCSTR())
 
 # Keyword parameters
-- `dtype::DataType` (default: `Float32`): the type to use for the resulting `LSH.LpHash`'s coefficients. Can be either `Float32` or `Float64`. You generally want to pick `dtype` to match the type of the data you're hashing.
+- $(DTYPE_DOCSTR($hashfn))
 - `r::Real` (default: `1.0`): a positive coefficient whose magnitude influences the collision rate. Larger values of `r` will increase the collision rate, even for distant points. See references for more information.
-- `resize_pow2::Bool` (default: `false`): affects the way in which the `LSH.LpHash` struct resizes to hash inputs of different sizes. If you think you'll be hashing inputs of many different sizes, it's more efficient to set `resize_pow2 = true`.
+- $(RESIZE_POW2_DOCSTR($hashfn))
 
 # Examples
-Construct an `LSH.LpHash` by calling `L1Hash` or `L2Hash` with the number of hash functions you want to generate:
+Construct an `$($hashfn)` with the number of hash functions you want to generate:
 
 ```jldoctest; setup = :(using LSH)
-julia> hashfn = L1Hash();
-
-julia> hashfn.power == 1 &&
-       n_hashes(hashfn) == 1 &&
-       similarity(hashfn) == ℓ1
-true
-
-julia> hashfn = L2Hash(128);
+julia> hashfn = $($hashfn)(128);
 
-julia> hashfn.power == 2 &&
+julia> hashfn.power == $($power) &&
        n_hashes(hashfn) == 128 &&
-       similarity(hashfn) == ℓ2
+       similarity(hashfn) == $($sim)
 true
 ```
 
 After creating a hash function, you can compute hashes with `hashfn(x)`:
 
 ```jldoctest; setup = :(using LSH)
-julia> hashfn = L1Hash(20);
+julia> hashfn = $($hashfn)(20);
 
 julia> x = rand(4);
 
@@ -133,14 +133,12 @@ julia> hashes = hashfn(x);
 
 # References
 
-```
-Datar, Mayur & Indyk, Piotr & Immorlica, Nicole & Mirrokni, Vahab. (2004). Locality-sensitive hashing scheme based on p-stable distributions. Proceedings of the Annual Symposium on Computational Geometry. 10.1145/997817.997857.
-```
+- Datar, Mayur & Indyk, Piotr & Immorlica, Nicole & Mirrokni, Vahab. (2004). *Locality-sensitive hashing scheme based on p-stable distributions*. Proceedings of the Annual Symposium on Computational Geometry. 10.1145/997817.997857.
 
-See also: [`ℓp`](@ref), [`ℓ1`](@ref), [`ℓ2`](@ref)
-""" L1Hash
-
-@doc (@doc L1Hash) L2Hash
+See also: [`$($sim)`](@ref ℓp)
+""" $hashfn
+    end |> eval
+end
 
 #========================
 Helper functions for LpHash

src/hashes/lphash.jl

@@ -24,14 +24,14 @@ struct MinHash{T, I <: Union{UInt32,UInt64}} <: SymmetricLSHFunction
 end
 
 """
-    MinHash(n_hashes::Integer = 1;
+    MinHash(n_hashes::Integer = $(DEFAULT_N_HASHES);
             dtype::DataType = Any,
             symbols::Union{Vector,Set} = Set())
 
 Construct a locality-sensitive hash function for Jaccard similarity.
 
 # Arguments
-- `n_hashes::Integer` (default: `1`): the number of hash functions to generate.
+- $(N_HASHES_DOCSTR())
 
 # Keyword parameters
 - `dtype::DataType` (default: `Any`): the type of symbols in the sets you're hashing. This is overriden by the data type contained in `symbols` when `symbols` is non-empty.
@@ -75,9 +75,7 @@ julia> hashfn(Set(["a", "b", "c"]));
 ```
 
 # References
-```
-Broder, A. "On the resemblance and containment of documents". Compression and Complexity of Sequences: Proceedings, Positano, Amalfitan Coast, Salerno, Italy, June 11-13, 1997. doi:10.1109/SEQUEN.1997.666900.
-```
+- Broder, A. *On the resemblance and containment of documents*. Compression and Complexity of Sequences: Proceedings, Positano, Amalfitan Coast, Salerno, Italy, June 11-13, 1997. doi:10.1109/SEQUEN.1997.666900.
 
 See also: [`jaccard`](@ref)
 """
@@ -92,7 +90,7 @@ function MinHash(args...;
     end
 end
 
-function MinHash{T}(n_hashes::Integer = 1;
+function MinHash{T}(n_hashes::Integer = DEFAULT_N_HASHES;
                     symbols::C = Set{T}()) where {T, C <: Union{Vector{<:T},Set{<:T}}}
 
     fixed_symbols = (length(symbols) > 0)