Remove confusion in gap interface conversion method

src/sage/algebras/quantum_groups/quantum_group_gap.py

@@ -198,7 +198,7 @@ def gap(self):
         """
         return self._libgap
 
-    _libgap_ = _gap_ = gap
+    _libgap_ = gap
 
     def _add_(self, other):
         r"""
@@ -432,7 +432,7 @@ def gap(self):
         """
         return self._libgap
 
-    _libgap_ = _gap_ = gap
+    _libgap_ = gap
 
     def cartan_type(self):
         """
@@ -1602,7 +1602,7 @@ def gap(self):
         """
         return self._libgap
 
-    _libgap_ = _gap_ = gap
+    _libgap_ = gap
 
     def _element_constructor_(self, elt):
         """

src/sage/combinat/designs/incidence_structures.py

@@ -43,12 +43,13 @@
 from sage.misc.latex import latex
 from sage.misc.lazy_import import lazy_import
 from sage.rings.integer import Integer
+from sage.structure.sage_object import SageObject
 from sage.sets.set import Set
 
 lazy_import('sage.libs.gap.libgap', 'libgap')
 
 
-class IncidenceStructure:
+class IncidenceStructure(SageObject):
     r"""
     A base class for incidence structures (i.e. hypergraphs, i.e. set systems)
 
@@ -1049,14 +1050,25 @@
         B = self._blocks
         return all(B[i] != B[i + 1] for i in range(len(B) - 1))
 
-    def _gap_(self):
+    def _gap_init_(self):
         """
         Return the GAP string describing the design.
 
         EXAMPLES::
 
+            sage: # optional - gap_package_design
             sage: BD = IncidenceStructure(7,[[0,1,2],[0,3,4],[0,5,6],[1,3,5],[1,4,6],[2,3,6],[2,4,5]])
-            sage: BD._gap_()
+            sage: gap.load_package("design")
+            sage: gap(BD)
+            rec(
+              blocks := [ [ 1, 2, 3 ], [ 1, 4, 5 ], [ 1, 6, 7 ], [ 2, 4, 6 ],
+                  [ 2, 5, 7 ], [ 3, 4, 7 ], [ 3, 5, 6 ] ],
+              isBlockDesign := true,
+              v := 7 )
+
+        TESTS::
+
+            sage: BD._gap_init_()
             'BlockDesign(7,[[1, 2, 3], [1, 4, 5], [1, 6, 7], [2, 4, 6], [2, 5, 7], [3, 4, 7], [3, 5, 6]])'
         """
         v = self.num_points()

src/sage/groups/class_function.py

@@ -144,7 +144,7 @@
         """
         return str(self._gap_classfunction)
 
-    def _gap_(self, *args):
+    def _gap_(self, gap):
         r"""
         Coerce ``self`` into a GAP element.
 
@@ -156,9 +156,9 @@
             Character of Cyclic group of order 4 as a permutation group
             sage: type(_)
             <class 'sage.groups.class_function.ClassFunction_gap'>
             sage: chi._gap_()
             ClassFunction( CharacterTable( Group( [ (1,2,3,4) ] ) ), [ 1, -1, 1, -1 ] )
             sage: type(_)
             <class 'sage.interfaces.gap.GapElement'>
         """
         return self._gap_classfunction
@@ -832,7 +832,7 @@
         """
         return self._gap_classfunction
 
-    gap = _gap_ = _libgap_
+    gap = _libgap_
 
     def _repr_(self):
         r"""

src/sage/groups/libgap_wrapper.pyx

@@ -294,7 +294,7 @@ class ParentLibGAP(SageObject):
         """
         return self._libgap
 
-    _libgap_ = _gap_ = gap
+    _libgap_ = gap
 
     def ngens(self):
         """
@@ -526,7 +526,7 @@ cdef class ElementLibGAP(MultiplicativeGroupElement):
         """
         return self._libgap
 
-    _libgap_ = _gap_ = gap
+    _libgap_ = gap
 
     def _test_libgap_conversion(self, **options):
         r"""

src/sage/interfaces/gap.py

@@ -6,18 +6,15 @@
 
 The GAP interface will only work if GAP is installed on your
 computer; this should be the case, since GAP is included with Sage.
-The interface offers three pieces of functionality:
+The interface offers two pieces of functionality:
 
 
 #. ``gap_console()`` -- a function that dumps you into
    an interactive command-line GAP session.
 
-#. ``gap(expr)`` -- evaluation of arbitrary GAP
-   expressions, with the result returned as a string.
-
-#. ``gap.new(expr)`` -- creation of a Sage object that
+#. ``gap(expr)`` -- creation of a Sage object that
    wraps a GAP object. This provides a Pythonic interface to GAP. For
-   example, if ``f=gap.new(10)``, then
+   example, if ``f=gap(10)``, then
    ``f.Factors()`` returns the prime factorization of
    `10` computed using GAP.
 

src/sage/libs/gap/util.pxd

@@ -42,5 +42,4 @@ cdef initialize()
 ### Evaluate string in GAP #################################################
 ############################################################################
 
-# Evaluate a string
 cdef Obj gap_eval(str gap_string) except? NULL

src/sage/libs/gap/util.pyx

@@ -293,6 +293,10 @@ cdef Obj gap_eval(str gap_string) except? NULL:
     r"""
     Evaluate a string in GAP.
 
+    This function cannot be used directly from Python, use
+    :meth:`~sage.libs.gap.libgap.Gap.eval` method on global ``libgap``
+    variable instead.
+
     INPUT:
 
     - ``gap_string`` -- string; a valid statement in GAP

src/sage/structure/sage_object.pyx

@@ -741,17 +741,84 @@ cdef class SageObject:
         return True
 
     def _gap_(self, G=None):
+        """
+        Return a Gap object.
+
+        Unlike :meth:`_libgap_`, this method returns an instance of
+        :class:`sage.interfaces.gap.GapElement`, which wraps an object
+        in the GAP interpreter spawned as a subprocess of Sage.
+
+        Typically you should not need to call this method directly,
+        instead just call :mod:`~sage.interfaces.gap`
+        on the object. See example below.
+
+        EXAMPLES::
+
+            sage: a = gap(2/3); a
+            2/3
+            sage: type(a)
+            <class 'sage.interfaces.gap.GapElement'>
+
+            sage: a = (2/3)._gap_(); a
+            2/3
+            sage: type(a)
+            <class 'sage.interfaces.gap.GapElement'>
+        """
         if G is None:
             import sage.interfaces.gap
             G = sage.interfaces.gap.gap
         return self._interface_(G)
 
     def _gap_init_(self):
+        """
+        Return a string that provides a representation of ``self`` in GAP.
+
+        This method is indirectly used by :meth:`_libgap_` and :meth:`_gap_`
+        by essentially passing their output to
+        :meth:`libgap.eval <sage.libs.gap.libgap.Gap.eval>`
+        and :mod:`~sage.interfaces.gap` respectively,
+        unless the subclass overrides them with more efficient variants.
+
+        EXAMPLES::
+
+            sage: (2/3)._gap_init_()
+            '2/3'
+            sage: Zmod(4)._gap_init_()
+            'ZmodnZ(4)'
+        """
         import sage.interfaces.gap
         I = sage.interfaces.gap.gap
         return self._interface_init_(I)
 
     def _libgap_(self):
+        """
+        Return a libgap object.
+
+        Unlike :meth:`_gap_`, this method returns an instance of
+        :class:`sage.libs.gap.libgap.GapElement`, which wraps an object
+        in libgap embedded in Sage. As explained in
+        :mod:`sage.libs.gap.libgap`, this is much faster.
+
+        Typically you should not need to call this method directly,
+        instead use :mod:`~sage.libs.gap.libgap`. See example below.
+
+        By default, this method makes use of :meth:`_gap_init_`.
+        Subclasses could override this method to provide a more efficient
+        implementation.
+
+        EXAMPLES::
+
+            sage: a = libgap(2/3); a
+            2/3
+            sage: type(a)
+            <class 'sage.libs.gap.element.GapElement_Rational'>
+
+        TESTS::
+
+            sage: from sage.libs.gap.element import GapElement
+            sage: isinstance(a, GapElement)
+            True
+        """
         from sage.libs.gap.libgap import libgap
         return libgap.eval(self)