Documentation and Convenience wrappers

README.md

@@ -2,6 +2,18 @@ A Julia library to handle projections on manifolds. This is useful for minimizin
 
 Currently, the sphere `{x ∈ K^n, ||x|| = r}` and the Stiefel manifold `{X ∈ K^{n × m}, X'*X = I}` as well as independent copies of these manifolds are supported.
 
+The projections implemented are `retract` and `project_tangent`.
+
+```
+retract(M::Manifold, x) = retract!(M, copy(x))
+```
+retracts the given point `x` back onto the Manifold `M`.
+```
+project_tangent(M::Manifold, g, x) = project_tangent!(M, copy(g), x)
+```
+Projects the given vector `g` into the tangent space on the Manifold `M` around the point `x`.
+`x` is assumed to lie on the manifold. This is not checked!
+
 Example usage:
 
 ```julia

src/ManifoldProjections.jl

@@ -21,7 +21,13 @@ end
 
 # fallback for out-of-place ops
 retract(M::Manifold, x) = retract!(M, copy(x))
+
+"""
+    project_tangent(M::Manifold, g, x)
+Return the projection of the given vector `g` into the tangent space on the Manifold `M` around the point `x` (assumed to lie on `M`).
+"""
 project_tangent(M::Manifold, g, x) = project_tangent!(M, copy(g), x)
+function project_tangent!(M::Manifold, g, x) end
 
 # Fake objective function implementing a retraction
 mutable struct ManifoldObjective{T<:NLSolversBase.AbstractObjective} <: NLSolversBase.AbstractObjective
@@ -108,11 +114,8 @@ Multiple copies of the same manifold. Points are stored as inner_dims x outer_di
 e.g. the product of 2x2 Stiefel manifolds of dimension N x n would be a N x n x 2 x 2 matrix.
 """
 struct PowerManifold<:Manifold
-    "Type of embedded manifold"
     inner_manifold::Manifold
-    "Dimension of the embedded manifolds"
     inner_dims::Tuple
-    "Number of embedded manifolds"
     outer_dims::Tuple
 end
 function retract!(m::PowerManifold, x)