Add docs for LSHFunction(). Add a page for the LSHFunction API, and a page stub for performance tips.

Author: kernelmethod

docs/make.jl

@@ -12,11 +12,13 @@ makedocs(
     format   = Documenter.HTML(),
     modules  = [LSH],
     pages    = ["Home" => "index.md",
+                "The LSHFunction API" => "lshfunction_api.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")]
+                    "Inner product similarity" => joinpath("similarities", "inner_prod.md")],
+                "Performance tips" => "performance.md",
                ]
 )
 

docs/src/index.md

@@ -3,13 +3,13 @@
 LSH.jl is a Julia package for performing [locality-sensitive hashing](https://en.wikipedia.org/wiki/Locality-sensitive_hashing) with various similarity functions.
 
 ## Introduction
-One of the simplest methods for classifying, categorizing, and grouping data is to measure how similarities pairs of data points are. For instance, the classical [``k``-nearest neighbors algorithm](https://en.wikipedia.org/wiki/K-nearest_neighbors_algorithm) takes a similarity function
+One of the simplest methods for classifying, categorizing, and grouping data is to measure how similarities pairs of data points are. For instance, the classical [``k``-nearest neighbors algorithm](https://en.wikipedia.org/wiki/K-nearest_neighbors_algorithm) searches an input space ``X`` by taking a query point ``x\in X`` and a similarity function
 
 ```math
 s:X\times X\to\mathbb{R}
 ```
 
-and a query point ``x\in X``, where ``X`` is the input space. It then computes ``s(x,y)`` for every point ``y`` in a database, and keeps the ``k`` points that are closest to ``x``.
+It then computes ``s(x,y)`` for every point ``y`` in a database, and keeps the ``k`` points that are closest to ``x``.
 
 Broadly, there are two computational issues with this approach:
 
@@ -23,8 +23,8 @@ LSH.jl is a package that provides definitions of locality-sensitive hash functio
 
 - Cosine similarity (`cossim`)
 - Jaccard similarity (`jaccard`)
-- ``L^1`` (Manhattan / "taxicab") distance (`ℓ1`)
-- ``L^2`` (Euclidean) distance (`ℓ2`)
+- ``\ell^1`` (Manhattan / "taxicab") distance (`ℓ1`)
+- ``\ell^2`` (Euclidean) distance (`ℓ2`)
 - Inner product (`inner_prod`)
 - Function-space hashes (`L1`, `L2`, and `cossim`)
 

docs/src/lshfunction_api.md

@@ -0,0 +1,10 @@
+# The LSHFunction API
+
+!!! warning "Under construction"
+    This section is currently being developed. If you're interested in helping write this section, feel free to [open a pull request](https://github.com/kernelmethod/LSH.jl/pulls); otherwise, please check back later.
+
+## API reference
+
+```@docs
+lsh_family
+```

docs/src/performance.md

@@ -0,0 +1,4 @@
+# Performance tips
+
+!!! warning "Under construction"
+    This section is currently being developed. If you're interested in helping write this section, feel free to [open a pull request](https://github.com/kernelmethod/LSH.jl/pulls); otherwise, please check back later.

src/LSHBase.jl

@@ -38,6 +38,7 @@ LSHFunction API
 ========================#
 
 macro register_similarity! end
+function LSHFunction end
 function lsh_family end
 
 #=

src/hashes/lshfunction.jl

@@ -4,6 +4,8 @@ Implementations of the LSHFunction() method for constructing new hash functions.
 
 ================================================================#
 
+using Markdown
+
 #========================
 Macros
 ========================#
@@ -88,9 +90,81 @@ end
 @reset_similarities!()
 
 #========================
-Documentation
+Documentation for various components of the LSHFunction API
 ========================#
 
+### similarity docs
+
+Docs.getdoc(::typeof(similarity)) = Markdown.parse("""
+    similarity(hashfn::LSHFunction)
+
+Returns the similarity function that `hashfn` hashes on.
+
+# Arguments
+- `hashfn::AbstractLSHFunction`: the hash function whose similarity we would like to retrieve.
+
+# Returns
+Returns a similarity function, which is one of the following:
+
+```
+$(join(available_similarities_as_strings(), "\n"))
+```
+
+# Examples
+```jldoctest; setup = :(using LSH)
+julia> hashfn = LSHFunction(cossim);
+
+julia> similarity(hashfn) == cossim
+true
+```
+""") # similarity
+
+### LSHFunction docs
+
+Docs.getdoc(::typeof(LSHFunction)) = Markdown.parse("""
+    LSHFunction(similarity, args...; kws...)
+
+Construct the default `LSHFunction` subtype that corresponds to the similarity function `similarity`.
+
+# Arguments
+- `similarity`: the similarity function you want to use. Can be any of the following:
+
+```
+$(join(available_similarities_as_strings(), "\n"))
+```
+
+- `args...`: arguments to pass on to the default `LSHFunction` constructor corresponding to `similarity`.
+- `kws...`: keyword parameters to pass on to the default `LSHFunction` constructor corresponding to `similarity`.
+
+# Returns
+Returns a subtype of `LSH.LSHFunction` that hashes the similarity function `similarity`.
+
+# Examples
+In the snippet below, we construct `$(lsh_family(cossim))` (the default hash function corresponding to cosine similarity) using `LSHFunction()`:
+
+```jldoctest; setup = :(using LSH)
+julia> hashfn = LSHFunction(cossim);
+
+julia> typeof(hashfn) <: $(lsh_family(cossim)) <: LSHFunction
+true
+```
+
+We can provide arguments and keyword parameters corresponding to the hash function that we construct:
+
+```jldoctest; setup = :(using LSH)
+julia> hashfn = LSHFunction(inner_prod, 100; dtype=Float64, maxnorm=10);
+
+julia> n_hashes(hashfn) == 100 &&
+       typeof(hashfn) <: SignALSH{Float64} &&
+       hashfn.maxnorm == 10
+true
+```
+
+See also: [`lsh_family`](@ref)
+""") # LSHFunction
+
+### lsh_family docs
+
 @doc """
     lsh_family(similarity)
 
@@ -120,4 +194,6 @@ else
 end
 )
 ```
+
+See also: [`LSHFunction`](@ref)
 """ lsh_family

src/similarities.jl

@@ -414,26 +414,3 @@ emd = wasserstein1_1d
 
 @doc (@doc wasserstein_1d)
 wasserstein2_2d(f, g) = wasserstein_1d(f, g, 2)
-
-#====================
-Definitions for similarity function-related components of the AbstractLSHFunction
-API.
-====================#
-
-# Define documentation for `similarity` manually so that we can dynamically
-# modify it through the available_similarities list.
-Docs.getdoc(::typeof(similarity)) = Markdown.parse("""
-    similarity(hashfn::AbstractLSHFunction)
-
-Returns the similarity function that the input `AbstractLSHFunction` hashes on.
-
-# Arguments
-- `hashfn::AbstractLSHFunction`: the hash function whose similarity we would like to retrieve.
-
-# Returns
-    Returns a similarity function, which is one of the following:
-
-```
-$(join(available_similarities_as_strings(), "\n"))
-```
-""")