From afac7de06d1af4326e8afe13d2c37dcb4eea9876 Mon Sep 17 00:00:00 2001
From: kalmar <kalmar@amu.edu.pl>
Date: Wed, 19 Jul 2017 23:00:44 +0200
Subject: [PATCH] doc strings for mul!s

---
 src/GroupRings.jl | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/src/GroupRings.jl b/src/GroupRings.jl
index 1038bbb..bd89396 100644
--- a/src/GroupRings.jl
+++ b/src/GroupRings.jl
@@ -321,6 +321,20 @@ end
 (+)(X::GroupRingElem, Y::GroupRingElem) = add(X,Y)
 (-)(X::GroupRingElem, Y::GroupRingElem) = add(X,-Y)
 
+doc"""
+    mul!{T}(result::AbstractArray{T},
+                 X::AbstractVector,
+                 Y::AbstractVector,
+                pm::Array{Int,2})
+> The most specialised multiplication for `X` and `Y` (`coeffs` of
+> `GroupRingElems`) using multiplication table `pm`.
+> Notes:
+> * this method will silently produce false results if `X[k]` is non-zero for
+> `k > size(pm,1)`.
+> * This method will fail if any zeros (i.e. uninitialised entries) are present
+> in `pm`.
+> * Use with extreme care!
+"""
 function mul!{T}(result::AbstractVector{T},
                       X::AbstractVector,
                       Y::AbstractVector,
@@ -339,6 +353,17 @@ function mul!{T}(result::AbstractVector{T},
    end
 end
 
+doc"""
+    mul!{T}(result::GroupRingElem{T},
+                 X::GroupRingElem,
+                 Y::GroupRingElem)
+> In-place multiplication for `GroupRingElem`s `X` and `Y`.
+> `mul!` will make use the initialised entries of `pm` attribute of
+> `parent(X)::GroupRing` (if available), and will compute and store in `pm` the
+> remaining products.
+> The method will fail with `KeyError` if product `X*Y` is not supported on
+> `parent(X).basis`.
+"""
 function mul!{T}(result::GroupRingElem{T}, X::GroupRingElem, Y::GroupRingElem)
    if result === X
       result = deepcopy(result)