DataVisitor docs and minor formatting changes

Author: Ivan Dlugos

lib/src/bindings/data_visitor.dart

@@ -2,6 +2,28 @@ import 'dart:ffi';
 import 'signatures.dart';
 import "package:ffi/ffi.dart" show allocate, free;
 
+/// This file implements C call forwarding using a trampoline approach.
+///
+/// When you want to pass a dart callback to a C function you cannot use lambdas and instead the callback must be
+/// a static function, otherwise `Pointer.fromFunction()` called with your function won't compile.
+/// Since static functions don't have any state, you must either rely on a global state or use a "userData" pointer
+/// pass-through functionality provided by a C function.
+///
+/// The DataVisitor class tries to alleviate the burden of managing this and instead allows using lambdas from
+/// user-code, internally mapping the C calls to the appropriate lambda.
+///
+/// Sample usage:
+///   final results = <T>[];
+///   final visitor = DataVisitor((Pointer<Uint8> dataPtr, int length) {
+///     final bytes = dataPtr.asTypedList(length);
+///     results.add(_fbManager.unmarshal(bytes));
+///     return true; // return value usually indicates to the C function whether it should continue.
+///   });
+///
+///   final err = bindings.obx_query_visit(_cQuery, visitor.fn, visitor.userData, offset, limit);
+///   visitor.close(); // make sure to close the visitor, unregistering the callback it from the forwarder
+///   checkObx(err);
+
 int _lastId = 0;
 final _callbacks = <int, bool Function(Pointer<Uint8> dataPtr, int length)>{};
 

lib/src/box.dart

@@ -172,29 +172,29 @@ class Box<T> {
         } finally {
           bindings.obx_bytes_array_free(bytesArray);
         }
-      }
-
-      final results = <T>[];
-      final visitor = DataVisitor((Pointer<Uint8> dataPtr, int length) {
-        if (dataPtr == null || dataPtr.address == 0 || length == 0) {
-          if (allowMissing) {
-            results.add(null);
-            return true;
-          } else {
-            throw Exception('Object not found');
+      } else {
+        final results = <T>[];
+        final visitor = DataVisitor((Pointer<Uint8> dataPtr, int length) {
+          if (dataPtr == null || dataPtr.address == 0 || length == 0) {
+            if (allowMissing) {
+              results.add(null);
+              return true;
+            } else {
+              throw Exception('Object not found');
+            }
           }
-        }
-        final bytes = dataPtr.asTypedList(length);
-        results.add(_fbManager.unmarshal(bytes));
-        return true;
-      });
+          final bytes = dataPtr.asTypedList(length);
+          results.add(_fbManager.unmarshal(bytes));
+          return true;
+        });
 
-      try {
-        cVisit(visitor);
-      } finally {
-        visitor.close();
+        try {
+          cVisit(visitor);
+        } finally {
+          visitor.close();
+        }
+        return results;
       }
-      return results;
     });
   }