Modify pointer docs in response to PR #1159 feedback

Author: gmarkall

docs/source/user-guide/deprecation.rst

@@ -34,17 +34,17 @@ Although Opaque Pointers are already the default in LLVM 15, llvmlite still used
 Typed Pointers by default with LLVM 15 in llvmlite 0.44.
 
 The binding layer will move to using Opaque Pointers. The IR layer will still
-support both Typed and Opaque Pointers, defaulting to Typed Pointers. This
-allows llvmlite to continue being used with LLVM-based projects that use an
-older LLVM version, such as `NVVM
+support both Typed and Opaque Pointers, defaulting to Typed Pointers when
+pointee types are provided. This allows llvmlite to continue being used with
+LLVM-based projects that use an older LLVM version, such as `NVVM
 <https://docs.nvidia.com/cuda/nvvm-ir-spec/>`_.
 
 Examples(s) of the impact
 -------------------------
 
-In a future release of llvmlite, code that uses llvmlite to work with pointers
-or to parse assembly that uses pointers will break if not modified to use
-Opaque Pointers.
+In a future release, code that uses llvmlite to work with Typed Pointers or
+generate IR with Typed Pointers will break if not modified to use Opaque
+Pointers.
 
 In the meantime, IR generated by the IR layer and parsed by the binding layer
 will be auto-upgraded to use Opaque Pointers transparently; no action is
@@ -53,7 +53,7 @@ required by the user.
 Schedule
 --------
 
-- In llvmlite 0.45, support for Opaque Pointers in the binding layer will be
+- In llvmlite 0.45, support for Typed Pointers in the binding layer will be
   removed. The IR layer will still use Typed Pointers by default.
 - In a future version of llvmlite (>= 0.46), the IR layer will use Opaque
   Pointers by default.

docs/source/user-guide/ir/types.rst

@@ -101,15 +101,13 @@ Pointer Types
 =============
 
 The IR layer presently supports both *Typed Pointers* and *Opaque Pointers*.
-Typed Pointers are currently the default; Opaque Pointers will become the
-default in future, and support for Typed Pointers will be eventually be
-removed.
+Support for Typed Pointers will be eventually be removed.
 
 .. note::
    Further details of the migration to Opaque Pointers are outlined in the
    section on :ref:`deprecation-of-typed-pointers`.
 
-When Typed Pointers are enabled, the pointer type is represented using:
+Typed Pointers are created using:
 
 .. class:: PointerType(pointee, addrspace=0)
 
@@ -127,8 +125,8 @@ When Typed Pointers are enabled, the pointer type is represented using:
 
         The type pointed to.
 
-Opaque Pointers can be enabled in the IR layer by setting the environment
-variable:
+Printing of Typed Pointers as Opaque Pointers can be enabled by setting the
+environment variable:
 
 .. code:: bash
 
@@ -144,8 +142,7 @@ llvmlite, but prior to using any of its functionality. For example:
 
    # ... continue using llvmlite ...
 
-When Opaque Pointers are enabled (by disabling Typed Pointers), the pointer
-type is represented using:
+Opaque Pointers can be created by using:
 
 .. class:: PointerType(addrspace=0)
    :no-index: