docs: improve apriltag_detector_detect comment

apriltag.h

@@ -255,10 +255,17 @@ void apriltag_detector_clear_families(apriltag_detector_t *td);
 // apriltag_family_t used to initialize it.)
 void apriltag_detector_destroy(apriltag_detector_t *td);
 
-// Detect tags from an image and return an array of
-// apriltag_detection_t*. You can use apriltag_detections_destroy to
-// free the array and the detections it contains, or call
-// _detection_destroy and zarray_destroy yourself.
+// Detect tags in a grayscale 8-bit image.
+//
+// Parameters:
+//   td      - A configured detector
+//   im_orig - A grayscale 8-bit image to search. 
+//
+// Returns a zarray_t* containing apriltag_detection_t* pointers, one per
+// detected tag. The array may be empty but is never NULL. The caller is
+// responsible for freeing the result: use apriltag_detections_destroy() to
+// free both the array and all detections, or call apriltag_detection_destroy()
+// on each element then zarray_destroy() separately.
 zarray_t *apriltag_detector_detect(apriltag_detector_t *td, image_u8_t *im_orig);
 
 // Call this method on each of the tags returned by apriltag_detector_detect