Add more docs to DragTraget.builder (flutter#151447)

Clarifications and changing a reference to a deprecated member.

Author: eseidel

packages/flutter/lib/src/widgets/drag_target.dart

@@ -39,9 +39,10 @@ typedef DragTargetAcceptWithDetails<T> = void Function(DragTargetDetails<T> deta
 /// Signature for building children of a [DragTarget].
 ///
 /// The `candidateData` argument contains the list of drag data that is hovering
-/// over this [DragTarget] and that has passed [DragTarget.onWillAccept]. The
-/// `rejectedData` argument contains the list of drag data that is hovering over
-/// this [DragTarget] and that will not be accepted by the [DragTarget].
+/// over this [DragTarget] and that has passed
+/// [DragTarget.onWillAcceptWithDetails]. The `rejectedData` argument contains
+/// the list of drag data that is hovering over this [DragTarget] and that will
+/// not be accepted by the [DragTarget].
 ///
 /// Used by [DragTarget.builder].
 typedef DragTargetBuilder<T> = Widget Function(BuildContext context, List<T?> candidateData, List<dynamic> rejectedData);
@@ -633,6 +634,20 @@ class DragTarget<T extends Object> extends StatefulWidget {
   ///
   /// The builder can build different widgets depending on what is being dragged
   /// into this drag target.
+  ///
+  /// [onWillAccept] or [onWillAcceptWithDetails] is called when a draggable
+  /// enters the target. If true, then the data will appear in `candidateData`,
+  /// else in `rejectedData`.
+  ///
+  /// Typically the builder will check `candidateData` and `rejectedData` and
+  /// build a widget that indicates the result of dropping the `candidateData`
+  /// onto this target.
+  ///
+  /// The `candidateData` and `rejectedData` are [List] types to support multiple
+  /// simultaneous drags.
+  ///
+  /// If unexpected `null` values in `candidateData` or `rejectedData`, ensure
+  /// that the `data` argument of the [Draggable] is not `null`.
   final DragTargetBuilder<T> builder;
 
   /// Called to determine whether this widget is interested in receiving a given