Improve documentation of various gap-related methods

Author: user202729

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,96 @@ 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.
+
+        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'>
+
+        ``GapElement_rational`` is a subclass of ``GapElement``::
+
+            sage: from sage.libs.gap.element import GapElement
+            sage: isinstance(a, GapElement)
+            True
+
+        The difference between ``libgap`` and ``libgap.eval`` is demonstrated below::
+
+            sage: libgap("1+2")
+            "1+2"
+            sage: libgap.eval("1+2")
+            3
+
+        Nonetheless, when the argument to ``libgap.eval`` is not a string,
+        its behavior is identical to ``libgap``::
+
+            sage: libgap.eval(2/3)
+            2/3
+        """
         from sage.libs.gap.libgap import libgap
         return libgap.eval(self)