get rid of Markdown docstrings

Project.toml

@@ -6,7 +6,6 @@ version = "0.4.2"
 [deps]
 AbstractAlgebra = "c3fe647b-3220-5bb0-a1ea-a7954cac585d"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
-Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 
 [compat]
 AbstractAlgebra = "^0.9.0"

src/DirectPower.jl

@@ -6,9 +6,9 @@ export DirectPowerGroup, DirectPowerGroupElem
 #
 ###############################################################################
 
-@doc doc"""
+"""
     DirectPowerGroup(G::Group, n::Int) <: Group
-Implements `n`-fold direct product of `G`. The group operation is
+Return `n`-fold direct product of `G`. The group operation is
 `*` distributed component-wise, with component-wise identity as neutral element.
 """
 struct DirectPowerGroup{N, T<:Group} <: Group
@@ -70,11 +70,11 @@ Base.getindex(g::DirectPowerGroupElem, i::Int) = g.elts[i]
 #
 ###############################################################################
 
-@doc doc"""
+"""
     (G::DirectPowerGroup)(a::Vector, check::Bool=true)
-> Constructs element of the $n$-fold direct product group `G` by coercing each
+Constructs element of the `n`-fold direct product group `G` by coercing each
-> element of vector `a` to `G.group`. If `check` flag is set to `false` neither
+element of vector `a` to `G.group`. If `check` flag is set to `false` neither
-> check on the correctness nor coercion is performed.
+check on the correctness nor coercion is performed.
 """
 function (G::DirectPowerGroup{N})(a::Vector, check::Bool=true) where N
    if check
@@ -131,20 +131,12 @@ end
 #
 ###############################################################################
 
-@doc doc"""
-    ==(g::DirectPowerGroup, h::DirectPowerGroup)
-> Checks if two direct product groups are the same.
-"""
 function (==)(G::DirectPowerGroup{N}, H::DirectPowerGroup{M}) where {N,M}
    N == M || return false
    G.group == H.group || return false
    return true
 end
 
-@doc doc"""
-    ==(g::DirectPowerGroupElem, h::DirectPowerGroupElem)
-> Checks if two direct product group elements are the same.
-"""
 (==)(g::DirectPowerGroupElem, h::DirectPowerGroupElem) = g.elts == h.elts
 
 ###############################################################################
@@ -153,11 +145,6 @@ end
 #
 ###############################################################################
 
-@doc doc"""
-    *(g::DirectPowerGroupElem, h::DirectPowerGroupElem)
-> Return the direct-product group operation of elements, i.e. component-wise
-> operation as defined by `operations` field of the parent object.
-"""
 function *(g::DirectPowerGroupElem{N}, h::DirectPowerGroupElem{N}, check::Bool=true) where N
    if check
       parent(g) == parent(h) || throw(DomainError(
@@ -168,10 +155,6 @@ end
 
 ^(g::DirectPowerGroupElem, n::Integer) = Base.power_by_squaring(g, n)
 
-@doc doc"""
-    inv(g::DirectPowerGroupElem)
-> Return the inverse of the given element in the direct product group.
-"""
 function inv(g::DirectPowerGroupElem{N}) where {N}
    return DirectPowerGroupElem(ntuple(i-> inv(g.elts[i]), N))
 end

src/Groups.jl

@@ -11,7 +11,6 @@ import Base: findfirst, findnext, findlast, findprev, replace
 import Base: deepcopy_internal
 
 using LinearAlgebra
-using Markdown
 
 export gens, FreeGroup, Aut, SAut
 
@@ -32,17 +31,11 @@ include("findreplace.jl")
 include("DirectPower.jl")
 include("WreathProducts.jl")
 
-
 ###############################################################################
 #
 #   String I/O
 #
 
-@doc doc"""
-    show(io::IO, W::GWord)
-> The actual string produced by show depends on the eltype of `W.symbols`.
-
-"""
 function Base.show(io::IO, W::GWord)
     if length(W) == 0
         print(io, "(id)")
@@ -64,16 +57,17 @@ end
 #   Misc
 #
 
-@doc doc"""
+"""
     gens(G::AbstractFPGroups)
-> returns vector of generators of `G`, as its elements.
+Return vector of generators of `G`, as its elements.
 """
 AbstractAlgebra.gens(G::AbstractFPGroup) = G.(G.gens)
 
-@doc doc"""
+"""
-    metric_ball(S::Vector{GroupElem}, center=Id; radius=2, op=*)
+    metric_ball(S::AbstractVector{<:GroupElem}
+        [, center=one(first(S)); radius=2, op=*])
 Compute metric ball as a list of elements of non-decreasing length, given the
-word-length metric on group generated by `S`. The ball is centered at `center`
+word-length metric on the group generated by `S`. The ball is centered at `center`
 (by default: the identity element). `radius` and `op` keywords specify the
 radius and multiplication operation to be used.
 """
@@ -90,12 +84,12 @@ function generate_balls(S::AbstractVector{T}, center::T=one(first(S));
     return c.*B, sizes
 end
 
-@doc doc"""
+"""
-    image(A::GWord, homomorphism; kwargs...)
+    image(w::GWord, homomorphism; kwargs...)
-Evaluate homomorphism `homomorphism` on a GWord `A`.
+Evaluate homomorphism `homomorphism` on a group word (element) `w`.
-`homomorphism` needs implement
+`homomorphism` needs to implement
-  > `hom(s; kwargs...)`,
+> `hom(w; kwargs...)`,
-where `hom(;kwargs...)` evaluates the value at the identity element.
+where `hom(;kwargs...)` returns the value at the identity element.
 """
 function image(w::GWord, hom; kwargs...)
     return reduce(*,

src/WreathProducts.jl

@@ -8,18 +8,17 @@ import AbstractAlgebra: AbstractPermutationGroup, AbstractPerm
 #
 ###############################################################################
 
-@doc doc"""
+"""
     WreathProduct(N, P) <: Group
-> Implements Wreath product of a group `N` by permutation group $P = S_n$,
+Return the wreath product of a group `N` by permutation group `P`, usually
-> usually written as $N \wr P$.
+written as `N ≀ P`. The multiplication inside wreath product is defined as
-> The multiplication inside wreath product is defined as
+>  `(n, σ) * (m, τ) = (n*σ(m), στ)`
->  >  `(n, σ) * (m, τ) = (n*σ(m), στ)`
+where `σ(m)` denotes the action (from the right) of the permutation group on
-> where `σ(m)` denotes the action (from the right) of the permutation group on
+`n-tuples` of elements from `N`
-> `n-tuples` of elements from `N`
 
 # Arguments:
-* `N::Group` : the single factor of the group $N$
+* `N::Group` : the single factor of the `DirectPower` group `N`
-* `P::Generic.PermGroup` : full `PermutationGroup`
+* `P::AbstractPermutationGroup` acting on `DirectPower` of `N`
 """
 struct WreathProduct{N, T<:Group, PG<:AbstractPermutationGroup} <: Group
    N::DirectPowerGroup{N, T}
@@ -71,25 +70,25 @@ function (G::WreathProduct{N})(g::WreathProductElem{N}) where {N}
    return WreathProductElem(n, p)
 end
 
-@doc doc"""
+"""
     (G::WreathProduct)(n::DirectPowerGroupElem, p::Generic.Perm)
-> Creates an element of wreath product `G` by coercing `n` and `p` to `G.N` and
+Create an element of wreath product `G` by coercing `n` and `p` to `G.N` and
-> `G.P`, respectively.
+`G.P`, respectively.
 """
 (G::WreathProduct)(n::DirectPowerGroupElem, p::Generic.Perm) = WreathProductElem(n,p)
 
 Base.one(G::WreathProduct) = WreathProductElem(one(G.N), one(G.P), false)
 
-@doc doc"""
+"""
     (G::WreathProduct)(p::Generic.Perm)
-> Returns the image of permutation `p` in `G` via embedding `p -> (id,p)`.
+Return the image of permutation `p` in `G` via embedding `p → (id,p)`.
 """
 (G::WreathProduct)(p::Generic.Perm) = G(one(G.N), p)
 
-@doc doc"""
+"""
     (G::WreathProduct)(n::DirectPowerGroupElem)
-> Returns the image of `n` in `G` via embedding `n -> (n,())`. This is the
+Return the image of `n` in `G` via embedding `n → (n, ())`. This is the
-> embedding that makes the sequence `1 -> N -> G -> P -> 1` exact.
+embedding that makes the sequence `1 → N → G → P → 1` exact.
 """
 (G::WreathProduct)(n::DirectPowerGroupElem) = G(n, one(G.P))
 
@@ -149,14 +148,12 @@ end
 
 (p::Generic.Perm)(n::DirectPowerGroupElem) = DirectPowerGroupElem(n.elts[p.d])
 
-@doc doc"""
+"""
     *(g::WreathProductElem, h::WreathProductElem)
-> Return the wreath product group operation of elements, i.e.
+Return the group operation of wreath product elements, i.e.
->
 > `g*h = (g.n*g.p(h.n), g.p*h.p)`,
->
+where `g.p(h.n)` denotes the action of `g.p::Generic.Perm` on
-> where `g.p(h.n)` denotes the action of `g.p::Generic.Perm` on
+`h.n::DirectPowerGroupElem` via standard permutation of coordinates.
-> `h.n::DirectPowerGroupElem` via standard permutation of coordinates.
 """
 function *(g::WreathProductElem, h::WreathProductElem)
    return WreathProductElem(g.n*g.p(h.n), g.p*h.p, false)
@@ -164,9 +161,9 @@ end
 
 ^(g::WreathProductElem, n::Integer) = Base.power_by_squaring(g, n)
 
-@doc doc"""
+"""
     inv(g::WreathProductElem)
-> Returns the inverse of element of a wreath product, according to the formula
+Return the inverse of element of a wreath product, according to the formula
 >   `g^-1 = (g.n, g.p)^-1 = (g.p^-1(g.n^-1), g.p^-1)`.
 """
 function inv(g::WreathProductElem)

src/freereduce.jl

@@ -40,11 +40,10 @@ end
 
 reduce!(w::GWord) = freereduce!(w)
 
-@doc doc"""
+"""
     reduce(w::GWord)
-> performs reduction/simplification of a group element (word in generators).
+performs reduction/simplification of a group element (word in generators).
-> The default reduction is the free group reduction
+The default reduction is the reduction in the free group reduction.
-> More specific procedures should be dispatched on `GWord`s type parameter.
+More specific procedures should be dispatched on `GWord`s type parameter.
-
 """
 reduce(w::GWord) = reduce!(deepcopy(w))

src/types.jl

@@ -1,31 +1,31 @@
 abstract type AbstractFPGroup <: Group end
 
-@doc doc"""
+"""
     ::GSymbol
-> Represents a syllable.
+Represents a syllable. Abstract type which all group symbols of
-> Abstract type which all group symbols of AbstractFPGroups should subtype. Each
+`AbstractFPGroups` should subtype. Each concrete subtype should implement fields:
-> concrete subtype should implement fields:
+ * `id` which is the `Symbol` representation/identification of a symbol
-> * `id` which is the `Symbol` representation/identification of a symbol
+ * `pow` which is the (multiplicative) exponent of a symbol.
-> * `pow` which is the (multiplicative) exponent of a symbol.
 """
 abstract type GSymbol end
 
 abstract type GWord{T<:GSymbol} <: GroupElem end
 
-@doc doc"""
+"""
     W::GroupWord{T} <: GWord{T<:GSymbol} <:GroupElem
-> Basic representation of element of a finitely presented group. `W.symbols`
+Basic representation of element of a finitely presented group.
-> fieldname contains particular group symbols which multiplied constitute a
+* `syllables(W)` return particular group syllables which multiplied constitute `W`
-> group element, i.e. a word in generators.
+group as a word in generators.
-> As reduction (inside group) of such word may be time consuming we provide
+* `parent(W)` return the parent group.
-> `savedhash` and `modified` fields as well:
-> hash (used e.g. in the `unique` function) is calculated by reducing the word,
-> setting `modified` flag to `false` and computing the hash which is stored in
-> `savedhash` field.
-> whenever word `W` is changed `W.modified` is set to `false`;
-> Future comparisons don't perform reduction (and use `savedhash`) as long as
-> `modified` flag remains `false`.
 
+As the reduction (inside the parent group) of word to normal form may be time
+consuming, we provide a shortcut that is useful in practice:
+`savehash!(W, h)` and `ismodified(W)` functions.
+When computing `hash(W)`, a reduction to normal form is performed and a
+persistent hash is stored inside `W`, setting `ismodified(W)` flag to `false`.
+This hash can be accessed by `savedhash(W)`.
+Future comparisons of `W` try not to perform reduction and use the stored hash as shortcut. Only when hashes collide reduction is performed. Whenever word `W` is
+changed, `ismodified(W)` returns `false` and stored hash is invalidated.
 """
 
 mutable struct GroupWord{T} <: GWord{T}