Improve docstrings for is_conjugate/is_conjugate_with_data.

src/Groups/GAPGroups.jl

@@ -710,7 +710,8 @@ end
     is_conjugate(G::GAPGroup, x::GAPGroupElem, y::GAPGroupElem)
 
 Return whether `x` and `y` are conjugate elements in `G`,
-i.e., there is an element $z$ in `G` such that `x^`$z$ equals `y`.
+i.e., there is an element `z` in `G` such that `x^z` equals `y`.
+To also return the element `z`, use [`is_conjugate_with_data`](@ref).
 """
 function is_conjugate(G::GAPGroup, x::GAPGroupElem, y::GAPGroupElem)
    if isdefined(G,:descr) && (G.descr == :GL || G.descr == :SL)
@@ -725,6 +726,8 @@ end
 If `x` and `y` are conjugate in `G`,
 return `(true, z)`, where `x^z == y` holds;
 otherwise, return `(false, nothing)`.
+If the conjugating element `z` is not needed,
+use [`is_conjugate`](@ref).
 """
 function is_conjugate_with_data(G::GAPGroup, x::GAPGroupElem, y::GAPGroupElem)
    if isdefined(G,:descr) && (G.descr == :GL || G.descr == :SL)
@@ -911,10 +914,13 @@ Base.:^(H::GAPGroup, y::GAPGroupElem) = conjugate_group(H, y)
 # (The name is confusing because it is not clear *of which group* the result
 # shall be a subgroup.)
 
-"""
+@doc raw"""
     is_conjugate(G::GAPGroup, H::GAPGroup, K::GAPGroup)
 
-Return whether `H` and `K` are conjugate subgroups in `G`.
+Return whether `H` and `K` are conjugate subgroups in `G`,
+i.e., whether there exists an element $z$ in  `G` such that
+`H^`$z$ equals `K`. To also return the element $z$
+use [`is_conjugate_with_data`](@ref).
 
 # Examples
 ```jldoctest
@@ -942,8 +948,10 @@ is_conjugate(G::GAPGroup, H::GAPGroup, K::GAPGroup) = GAPWrap.IsConjugate(G.X,H.
 """
     is_conjugate_with_data(G::Group, H::Group, K::Group)
 
-If `H` and `K` are conjugate subgroups in `G`, return `true, z`
-where `H^z = K`; otherwise, return `false, nothing`.
+If `H` and `K` are conjugate subgroups in `G`, return `(true, z)`
+where `H^z = K`; otherwise, return `(false, nothing)`.
+If the conjugating element `z` is not needed, use
+[`is_conjugate`](@ref).
 
 # Examples
 ```jldoctest

src/Groups/gsets.jl

@@ -241,7 +241,7 @@ function ^(omega::ElementOfGSet, g::T) where {T<:AbstractAlgebra.GroupElem}
     return ElementOfGSet(Omega, fun(omega.obj, g))
 end
 
-==(omega1::ElementOfGSet, omega2::ElementOfGSet) = 
+==(omega1::ElementOfGSet, omega2::ElementOfGSet) =
   ((omega1.gset == omega2.gset) && (omega1.obj == omega2.obj))
 
 function Base.hash(omega::ElementOfGSet, h::UInt)
@@ -687,6 +687,7 @@ end
 
 Return `true` if `omega1`, `omega2` are in the same orbit of `Omega`,
 and `false` otherwise.
+To also obtain a conjugating element use [`is_conjugate_with_data`](@ref).
 
 # Examples
 ```jldoctest
@@ -709,9 +710,10 @@ is_conjugate(Omega::GSet, omega1, omega2) = omega2 in orbit(Omega, omega1)
     is_conjugate_with_data(Omega::GSet, omega1, omega2)
 
 Determine whether `omega1`, `omega2` are in the same orbit of `Omega`.
-If yes, return `true, g` where `g` is an element in the group `G` of
+If yes, return `(true, g)` where `g` is an element in the group `G` of
 `Omega` that maps `omega1` to `omega2`.
-If not, return `false, nothing`.
+If not, return `(false, nothing)`.
+If the conjugating element `g` is not needed, use [`is_conjugate`](@ref).
 
 # Examples
 ```jldoctest