gh-39905: Improve documentation of various gap-related methods
    
As in the title.

There will be no visible change to the user because these methods all
start with `_`, only to Sage developers.

The reason is… there's a lot of confusion in downstream implementations,
so it looks like whoever initially wrote that code wasn't aware of the
convention. See #39908 .

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->

- [x] The title is concise and informative.
- [x] The description explains in detail what this PR is about.
- [ ] I have linked a relevant issue or discussion.
- [x] I have created tests covering the changes.
- [x] I have updated the documentation and checked the documentation
preview.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on. For example,
-->
<!-- - #12345: short description why this is a dependency -->
<!-- - #34567: ... -->
    
URL: #39905
Reported by: user202729
Reviewer(s): Frédéric Chapoton, user202729

Author: Release Manager

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

@@ -338,6 +338,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)