Add a bit of docs

Author: msimacek

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/modules/ctypes/PyCArgObject.java

@@ -63,5 +63,4 @@ public PyCArgObject(Object cls, Shape instanceShape) {
         obj = null;
         valuePointer = Pointer.NULL;
     }
-
 }

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/modules/ctypes/memory/Pointer.java

@@ -51,6 +51,11 @@
 import com.oracle.truffle.api.library.ExportLibrary;
 import com.oracle.truffle.api.library.ExportMessage;
 
+/**
+ * Pointer abstraction that should be accessed through {@link PointerNodes}. It supports storing
+ * byte-based data or other pointers, both of which can be converted in-place to native memory if
+ * needed (and native access is enabled).
+ */
 @ExportLibrary(InteropLibrary.class)
 public final class Pointer implements TruffleObject {
     public static final Pointer NULL = new Pointer(new NullStorage(), 0);
@@ -95,7 +100,7 @@ public static Pointer nativeMemory(Object nativePointer) {
         if (nativePointer instanceof Long value) {
             return nativeMemory((long) value);
         }
-        return new Pointer(new NFIPointerStorage(nativePointer), 0);
+        return new Pointer(new ObjectPointerStorage(nativePointer), 0);
     }
 
     public static Pointer pythonObject(Object object) {
@@ -258,10 +263,10 @@ public LongPointerStorage(long pointer) {
         }
     }
 
-    static final class NFIPointerStorage extends Storage {
+    static final class ObjectPointerStorage extends Storage {
         final Object pointer;
 
-        public NFIPointerStorage(Object pointer) {
+        public ObjectPointerStorage(Object pointer) {
             this.pointer = pointer;
         }
     }

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/modules/ctypes/memory/PointerNodes.java

@@ -9,8 +9,8 @@
 import com.oracle.graal.python.builtins.modules.ctypes.memory.Pointer.LongPointerStorage;
 import com.oracle.graal.python.builtins.modules.ctypes.memory.Pointer.MemoryBlock;
 import com.oracle.graal.python.builtins.modules.ctypes.memory.Pointer.MemoryViewStorage;
-import com.oracle.graal.python.builtins.modules.ctypes.memory.Pointer.NFIPointerStorage;
 import com.oracle.graal.python.builtins.modules.ctypes.memory.Pointer.NullStorage;
+import com.oracle.graal.python.builtins.modules.ctypes.memory.Pointer.ObjectPointerStorage;
 import com.oracle.graal.python.builtins.modules.ctypes.memory.Pointer.PointerArrayStorage;
 import com.oracle.graal.python.builtins.modules.ctypes.memory.Pointer.PythonObjectStorage;
 import com.oracle.graal.python.builtins.modules.ctypes.memory.Pointer.Storage;
@@ -660,7 +660,7 @@ public final Object execute(Node inliningTarget, Pointer ptr) {
         protected abstract Object execute(Node inliningTarget, MemoryBlock memory, Storage storage, int offset);
 
         @Specialization
-        static Object doNFIPointer(Node inliningTarget, @SuppressWarnings("unused") MemoryBlock memory, NFIPointerStorage storage, int offset) {
+        static Object doObjectPointer(Node inliningTarget, @SuppressWarnings("unused") MemoryBlock memory, ObjectPointerStorage storage, int offset) {
             if (offset != 0) {
                 throw PRaiseNode.raiseUncached(inliningTarget, NotImplementedError, ErrorMessages.CANNOT_APPLY_OFFSET_TO_AN_OBJECT_POINTER);
             }
@@ -679,7 +679,7 @@ public final long execute(Node inliningTarget, Pointer ptr) {
 
         @Specialization
         @SuppressWarnings("unused")
-        static long doNFIPointer(Node inliningTarget, MemoryBlock memory, NFIPointerStorage storage, int offset) {
+        static long doObjectPointer(Node inliningTarget, MemoryBlock memory, ObjectPointerStorage storage, int offset) {
             throw PRaiseNode.raiseUncached(inliningTarget, NotImplementedError, ErrorMessages.CANNOT_CONVERT_OBJECT_POINTER_TO_NATIVE);
         }
     }
@@ -704,7 +704,7 @@ void doNativeMemory(Node inliningTarget, LongPointerStorage storage, int offset)
 
         @Specialization
         @SuppressWarnings("unused")
-        void doNFIPointer(NFIPointerStorage storage, int offset) {
+        void doObjectPointer(ObjectPointerStorage storage, int offset) {
             /*
              * TODO This should call free using NFI. If it ever does, we should probably update
              * PointerReference to use a call target around this

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/modules/ctypes/memory/PointerReference.java

@@ -2,6 +2,12 @@
 
 import com.oracle.graal.python.runtime.AsyncHandler;
 
+/**
+ * Weak reference object that will deallocate possible native memory pointed to by a {@link Pointer}
+ * when given referent gets garbage collected. It is not necessary to keep a reference to this
+ * object after creating it, it stores a reference to itself into
+ * {@link AsyncHandler.SharedFinalizer} automatically.
+ */
 public class PointerReference extends AsyncHandler.SharedFinalizer.FinalizableReference {
 
     public PointerReference(Object referent, Pointer pointer, AsyncHandler.SharedFinalizer sharedFinalizer) {