Improve docstrings for is_conjugate/is_conjugate_with_data. (#3384)

src/Groups/GAPGroups.jl

@@ -724,7 +724,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)
@@ -739,6 +740,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)
@@ -925,10 +928,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
@@ -956,8 +962,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

@@ -719,6 +719,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
@@ -741,9 +742,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