documentation clean up

Author: njericha

src/Core/constraint.jl

@@ -200,7 +200,11 @@ end
 # It only returns a Bool rather than a number, but simplex! checks
 # if the output of the "norm" function equals 1, which is converted
 # to a Boolean True. Is there some way to treat this constraint better?
-"""all(isnonnegative, x) && sum(x) ≈ 1"""
+"""
+    isnonnegative_sumtoone(x)
+
+Short for `all(isnonnegative, x) && sum(x) ≈ 1`.
+"""
 isnonnegative_sumtoone(x) = all(isnonnegative, x) && sum(x) ≈ 1
 
 """

src/Core/decomposition.jl

@@ -106,10 +106,12 @@ of the decomposition.
 
 Example
 -------
+```julia
 (op1, op2) = contractions(D)
 (A, B, C) = factors(D)
 
-array(D) == (A op1 B) op2 C
+array(D) == op2(op1(A, B), C)
+```
 """
 contractions(D::AbstractDecomposition) = D.contractions
 

src/Core/factorize.jl

@@ -30,6 +30,8 @@ function factorize(Y; kwargs...)
 end
 
 """
+    _factorize(Y; kwargs...)
+
 Inner level function once keyword arguments are set
 """
 function _factorize(Y; kwargs...)
@@ -56,6 +58,8 @@ function _factorize(Y; kwargs...)
 end
 
 """
+    initialize(Y, kwargs)
+
 Main initialization function for `factorize`.
 """
 function initialize(Y, kwargs)
@@ -79,6 +83,8 @@ function initialize(Y, kwargs)
 end
 
 """
+    postprocess!(decomposition, Y, previous, parameters, stats_data, updateparameters!, getstats, kwargs)
+
 Any post algorithm processing that needs to be done in `factorize`.
 """
 function postprocess!(decomposition, Y, previous, parameters, stats_data, updateparameters!, getstats, kwargs)
@@ -266,7 +272,11 @@ function finalconstrain!(decomposition; constraints, final_constraints, kwargs..
 	return NamedTuple(kwargs) # Freeze Dict into a NamedTuple
 end
 
-"""The decomposition model Y will be factored into"""
+"""
+    initialize_decomposition(Y; decomposition, model, rank, kwargs...)
+
+The decomposition model Y will be factored into
+"""
 function initialize_decomposition(Y; decomposition, model, rank, kwargs...)
 	kwargs = Dict{Symbol,Any}(kwargs)
 	# have to add these keyword back since it was extracted by make_update # TODO check if I can safely remove these
@@ -282,6 +292,8 @@ function initialize_decomposition(Y; decomposition, model, rank, kwargs...)
 end
 
 """
+    make_update!(decomposition, Y; momentum, constraints, constrain_init, group_updates_by_factor, do_subblock_updates, kwargs...)
+
 What one iteration of the algorithm looks like.
 One iteration is likely a full cycle through each block or factor of the model.
 """
@@ -341,7 +353,11 @@ function make_update!(decomposition, Y; momentum, constraints, constrain_init, g
 	return update!, kwargs
 end
 
-"""The stats that will be saved every iteration"""
+"""
+    initialize_stats(decomposition, Y, previous, parameters; stats, kwargs...)
+
+The stats that will be saved every iteration
+"""
 function initialize_stats(decomposition, Y, previous, parameters; stats, kwargs...)
 	stat_functions = [S(; kwargs...) for S in stats] # construct the AbstractStats
 	#@show stat_functions
@@ -354,7 +370,11 @@ function initialize_stats(decomposition, Y, previous, parameters; stats, kwargs.
 	return stats_data, getstats
 end
 
-"""Keep track of one or more previous iterates"""
+"""
+    initialize_previous(decomposition, Y; previous_iterates::Integer, kwargs...)
+
+Keep track of one or more previous iterates
+"""
 function initialize_previous(decomposition, Y; previous_iterates::Integer, kwargs...)
 	previous = [deepcopy(decomposition) for _ in 1:previous_iterates] # TODO check if this should be copy?
 	if previous_iterates == 0
@@ -372,7 +392,11 @@ function initialize_previous(decomposition, Y; previous_iterates::Integer, kwarg
 	end
 end
 
-"""update parameters needed for the update"""
+"""
+    initialize_parameters(decomposition, Y, previous; momentum::Bool, random_order, recursive_random_order, kwargs...)
+
+update parameters needed for the update
+"""
 function initialize_parameters(decomposition, Y, previous; momentum::Bool, random_order, recursive_random_order, kwargs...)
 	# parameters for the update step are symbol => value pairs
 	# they are held in a dictionary since we may mutate these for ex. the stepsize

src/Core/multiscale.jl

@@ -221,7 +221,11 @@ function scale_constraints(Y, scale; continuous_dims, kwargs...)
     return kwargs[:constraints], kwargs
 end
 
-"""Use the same initialization as factorize() to get the expanded set of constraints"""
+"""
+    expand_decomposition_constraints(Y, kwargs)
+
+Use the same initialization as [`factorize`](@ref) to get the expanded set of constraints.
+"""
 function expand_decomposition_constraints(Y, kwargs)
     kwargs_copy = deepcopy(kwargs) # Don't mess up anything since the following functions mutate kwargs
     kwargs_copy = default_kwargs(Y; kwargs_copy...) # TODO Is there some way to clean this up?

src/Core/tensorproducts.jl

@@ -150,12 +150,12 @@ arguments as matrices in a Tucker decomposition.
 
 Example
 -------
-```
+```julia
 tuckerproduct(G, (A, B, C)) == G ×₁ A ×₂ B ×₃ C
 tuckerproduct(G, (A, B, C); exclude=2) == G ×₁ A ×₃ C
 tuckerproduct(G, (A, B, C); exclude=2, excludes_missing=false) == G ×₁ A ×₃ C
 tuckerproduct(G, (A, C); exclude=2, excludes_missing=true) == G ×₁ A ×₃ C
-````
+```
 """
 function tuckerproduct(core, matrices; exclude=nothing, excludes_missing=false)
     N = ndims(core)

src/Core/utils.jl

@@ -102,10 +102,18 @@ Base.min(A::AbstractArray, x::Number) = min.(A, x)
 
 # ( (x-1) % 4 +1, (x-1) ÷ 4 % 3 + 1, (x-1) ÷ 4 ÷ 3 % 2 + 1)
 
-"""Like `getindex` but returns the compliment to the index or indices requested."""
 getnotindex(A, i::Int; view=false) = view ? (@view A[eachindex(A) .!= i]) : A[eachindex(A) .!= i]
 getnotindex(A, I; view=false) = view ? (@view A[eachindex(A) .∉ (I,)]) : A[eachindex(A) .∉ (I,)]
 
+docs = """    getnotindex(A, i::Int; view=false)
+    getnotindex(A, I; view=false)
+
+Like `getindex` but returns the compliment to the index or indices requested.
+"""
+
+@doc docs getnotindex
+# Want both methods to receive this documentation
+
 """
     eachfibre(A::AbstractArray; n::Integer, kwargs...)
 
@@ -145,7 +153,11 @@ end
 
 #fullouter(v...) = reshape(kron(reverse(vec.(v))...),tuple(vcat(collect.(size.(v))...)...))
 
-"""Makes a Tuple of length n filled with `false`."""
+"""
+    false_tuple(n::Integer)
+
+Makes a Tuple of length n filled with `false`.
+"""
 false_tuple(n::Integer) = Tuple(fill(false, n))
 
 """
@@ -293,7 +305,7 @@ end
 
 Geometric mean of a collection: `prod(v)^(1/length(v))`.
 
-If prod(v) is detected to be 0 or Inf, the safer (but slower) implementation `exp(mean(log.(v)))` is used.
+If `prod(v)` is detected to be `0` or `Inf`, the safer (but slower) implementation `exp(mean(log.(v)))` is used.
 """
 function geomean(v)
     p = prod(v)
@@ -317,7 +329,7 @@ Like `foldl`, but with a different folding operation between each argument.
 
 Example
 =======
-```
+```julia-repl
 julia> multifoldl((+,*,-), (2,3,4,5))
 15