Remove suggestions to use internal functions (#2092)

filmor · web-flow · commit c2fa4677035e · 2023-01-29T15:00:14.000+01:00
Fixes #2091
diff --git a/doc/source/dotnet.rst b/doc/source/dotnet.rst
@@ -42,28 +42,39 @@ application.
 
 Before interacting with any of the objects or APIs provided by the
 ``Python.Runtime`` namespace, calling code must have acquired the Python
-global interpreter lock by calling the ``PythonEngine.AcquireLock``
-method. The only exception to this rule is the
-``PythonEngine.Initialize`` method, which may be called at startup
-without having acquired the GIL.
-
-When finished using Python APIs, managed code must call a corresponding
-``PythonEngine.ReleaseLock`` to release the GIL and allow other threads
-to use Python.
-
-A ``using`` statement may be used to acquire and release the GIL:
+global interpreter lock by ``using'' ``Py.GIL()``. The only exception to
+this rule is the ``PythonEngine.Initialize`` method, which may be called
+at startup without having acquired the GIL. The GIL is released again
+by disposing the return value of `Py.GIL()`:
 
 .. code:: csharp
 
    using (Py.GIL())
    {
        PythonEngine.Exec("doStuff()");
    }
+   
+   // or
+   {
+       using var _ = Py.GIL()
+       PythonEngine.Exec("doStuff()");
+   }
+   
+   // or
+   var gil = Py.GIL();
+   try
+   {
+       PythonEngine.Exec("doStuff()");
+   }
+   finally
+   {
+       gil.Dispose();
+   }
 
-The AcquireLock and ReleaseLock methods are thin wrappers over the
-unmanaged ``PyGILState_Ensure`` and ``PyGILState_Release`` functions
-from the Python API, and the documentation for those APIs applies to the
-managed versions.
+The ``Py.GIL()'' object is a thin wrapper over the unmanaged
+``PyGILState_Ensure`` (on construction) and ``PyGILState_Release`` (on
+disposal) functions from the Python API, and the documentation for those
+APIs applies to the managed versions.
 
 Passing C# Objects to the Python Engine
 ---------------------------------------
