From a54ebbcede5e5096024fa0fde12d94a3025097cb Mon Sep 17 00:00:00 2001
From: kalmar <kalmar@amu.edu.pl>
Date: Thu, 11 May 2017 18:10:46 +0200
Subject: [PATCH] docs and headers

---
 src/Groups.jl | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 58 insertions(+), 1 deletion(-)

diff --git a/src/Groups.jl b/src/Groups.jl
index 7636942..1bb6c3a 100644
--- a/src/Groups.jl
+++ b/src/Groups.jl
@@ -8,6 +8,11 @@ import Base: inv, reduce, *, ^
 import Base: findfirst, findnext
 import Base: deepcopy_internal
 
+###############################################################################
+#
+#   ParentType / ObjectType definition
+#
+###############################################################################
 
 doc"""
     ::GSymbol
@@ -48,12 +53,28 @@ end
 
 export GSymbol, GWord
 
+###############################################################################
+#
+#   Type and parent object methods
+#
+###############################################################################
 
 parent{T<:GSymbol}(w::GWord{T}) = w.parent
 
+###############################################################################
+#
+#   ParentType / ObjectType constructors
+#
+###############################################################################
+
 GWord{T<:GSymbol}(s::T) = GWord{T}(T[s])
 convert{T<:GSymbol}(::Type{GWord{T}}, s::T) = GWord{T}(T[s])
 
+###############################################################################
+#
+#   Basic manipulation
+#
+###############################################################################
 
 function hash(W::GWord, h::UInt)
     W.modified && reduce!(W)
@@ -108,8 +129,17 @@ doc"""
 """
 reduce(W::GWord) = reduce!(deepcopy(W))
 
+###############################################################################
+#
+#   String I/O
+#
+###############################################################################
 
+doc"""
+    show(io::IO, W::GWord)
+> The actual string produced by show depends on the eltype of W.symbols.
 
+"""
 function show(io::IO, W::GWord)
     if length(W) == 0
         print(io, "(id)")
@@ -118,6 +148,12 @@ function show(io::IO, W::GWord)
     end
 end
 
+###############################################################################
+#
+#   Comparison
+#
+###############################################################################
+
 function (==)(W::GWord, Z::GWord)
     parent(W) == parent(Z) || return false
     W.modified && reduce!(W) # reduce clears the flag and calculates savedhash
@@ -125,6 +161,12 @@ function (==)(W::GWord, Z::GWord)
     return W.savedhash == Z.savedhash && W.symbols == Z.symbols
 end
 
+###############################################################################
+#
+#   Binary operators
+#
+###############################################################################
+
 function r_multiply!(W::GWord, x; reduced::Bool=true)
     if length(x) > 0
         push!(W.symbols, x...)
@@ -184,6 +226,10 @@ end
 
 (^)(x::GWord, n::Integer) = power_by_squaring(x,n)
 
+###############################################################################
+#
+#   Inversion
+#
 ###############################################################################
 
 function inv{T}(W::GWord{T})
@@ -197,6 +243,12 @@ function inv{T}(W::GWord{T})
     end
 end
 
+###############################################################################
+#
+#   Replacement of symbols / sub-words
+#
+###############################################################################
+
 is_subsymbol(s::GSymbol, t::GSymbol) =
     s.str == t.str && (0 ≤ s.pow ≤ t.pow || 0 ≥ s.pow ≥ t.pow)
 
@@ -266,7 +318,12 @@ end
 
 replace_all(W::GWord, subst_dict::Dict{GWord, GWord}) = replace_all!(deepcopy(W), subst_dict)
 
-include("free_groups.jl")
+###############################################################################
+#
+#   Includes
+#
+###############################################################################
+
 include("automorphism_groups.jl")
 
 end # of module Groups