From 4a71b885eb95256e39efc326800ece5dd94c71e3 Mon Sep 17 00:00:00 2001
From: ThomasBreuer <sam@math.rwth-aachen.de>
Date: Wed, 30 Nov 2022 10:58:54 +0100
Subject: [PATCH] document `recursive` for `GAP.Obj` and `GAP.GapObj`

fixed #827
---
 src/types.jl | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/src/types.jl b/src/types.jl
index c1469c99..169fef50 100644
--- a/src/types.jl
+++ b/src/types.jl
@@ -94,6 +94,9 @@ However, this is restricted to outputs that actually are of type `GapObj`.
 To also deal with GAP integers, finite field elements and booleans, use
 [`GAP.Obj`](@ref) instead.
 
+The keyword argument `recursive` with value `true` can be used to force
+recursive conversion of nested Julia objects (arrays, tuples, dictionaries).
+
 # Examples
 ```jldoctest
 julia> GapObj(1//3)
@@ -102,6 +105,12 @@ GAP: 1/3
 julia> GapObj([1 2; 3 4])
 GAP: [ [ 1, 2 ], [ 3, 4 ] ]
 
+julia> GAP.GapObj([[1, 2], [3, 4]])
+GAP: [ <Julia: [1, 2]>, <Julia: [3, 4]> ]
+
+julia> GAP.GapObj([[1, 2], [3, 4]], recursive = true)
+GAP: [ [ 1, 2 ], [ 3, 4 ] ]
+
 julia> GapObj(42)
 ERROR: TypeError: in typeassert, expected GapObj, got a value of type Int64
 
@@ -119,6 +128,9 @@ Moreover, it can be used as a constructor,
 in order to convert Julia objects to GAP objects,
 whenever a suitable conversion has been defined.
 
+The keyword argument `recursive` with value `true` can be used to force
+recursive conversion of nested Julia objects (arrays, tuples, dictionaries).
+
 # Examples
 ```jldoctest
 julia> GAP.Obj(1//3)
@@ -127,6 +139,12 @@ GAP: 1/3
 julia> GAP.Obj([1 2; 3 4])
 GAP: [ [ 1, 2 ], [ 3, 4 ] ]
 
+julia> GAP.Obj([[1, 2], [3, 4]])
+GAP: [ <Julia: [1, 2]>, <Julia: [3, 4]> ]
+
+julia> GAP.Obj([[1, 2], [3, 4]], recursive = true)
+GAP: [ [ 1, 2 ], [ 3, 4 ] ]
+
 julia> GAP.Obj(42)
 42