Fix retain_grad() documentation for leaf vs non-leaf tensors (#3657)

The documentation incorrectly stated that calling retain_grad() on a
non-leaf node results in a no-op. This is misleading because:

- retain_grad() on a non-leaf tensor with requires_grad=True correctly
retains gradients (not a no-op)
- retain_grad() on a leaf tensor is a no-op (already retains by default)
- retain_grad() on a tensor with requires_grad=False throws an error

Updated the documentation and summary table to accurately reflect this
behavior.

Fixes #3652

## Description
<!--- Describe your changes in detail -->

## Checklist
<!--- Make sure to add `x` to all items in the following checklist: -->
- [ ] The issue that is being fixed is referred in the description (see
above "Fixes #ISSUE_NUMBER")
- [ ] Only one issue is addressed in this pull request
- [ ] Labels from the issue that this PR is fixing are added to this
pull request
- [ ] No unnecessary issues are included into this pull request.


cc @jbschlosser

Co-authored-by: Svetlana Karslioglu <[email protected]>
Co-authored-by: sekyondaMeta <[email protected]>

Author: 3 people

beginner_source/understanding_leaf_vs_nonleaf_tutorial.py

@@ -265,8 +265,10 @@
 #
 #    Computational graph after backward pass
 #
-# If you call ``retain_grad()`` on a non-leaf node, it results in a no-op.
-# If we call ``retain_grad()`` on a node that has ``requires_grad=False``,
+# If you call ``retain_grad()`` on a leaf tensor, it results in a no-op
+# since leaf tensors already retain their gradients by default (when
+# ``requires_grad=True``).
+# If we call ``retain_grad()`` on a tensor that has ``requires_grad=False``,
 # PyTorch actually throws an error, since it can’t store the gradient if
 # it is never calculated.
 #
@@ -298,13 +300,13 @@
 # +----------------+------------------------+------------------------+---------------------------------------------------+-------------------------------------+
 # |  ``is_leaf``   |   ``requires_grad``    |   ``retains_grad``     |  ``require_grad()``                               |   ``retain_grad()``                 |
 # +================+========================+========================+===================================================+=====================================+
-# | ``True``       | ``False``              | ``False``              | sets ``requires_grad`` to ``True`` or ``False``   | no-op                               |
+# | ``True``       | ``False``              | ``False``              | sets ``requires_grad`` to ``True`` or ``False``   | throws error                        |
 # +----------------+------------------------+------------------------+---------------------------------------------------+-------------------------------------+
-# | ``True``       | ``True``               | ``False``              | sets ``requires_grad`` to ``True`` or ``False``   | no-op                               |
+# | ``True``       | ``True``               | ``False``              | sets ``requires_grad`` to ``True`` or ``False``   | no-op (already retains)             |
 # +----------------+------------------------+------------------------+---------------------------------------------------+-------------------------------------+
 # | ``False``      | ``True``               | ``False``              | no-op                                             | sets ``retains_grad`` to ``True``   |
 # +----------------+------------------------+------------------------+---------------------------------------------------+-------------------------------------+
-# | ``False``      | ``True``               | ``True``               | no-op                                             | no-op                               |
+# | ``False``      | ``True``               | ``True``               | no-op                                             | no-op (already retains)             |
 # +----------------+------------------------+------------------------+---------------------------------------------------+-------------------------------------+
 #