Index: modules/field/field.attach.inc
===================================================================
RCS file: /cvs/drupal/drupal/modules/field/field.attach.inc,v
retrieving revision 1.91
diff -u -F '^[fc]' -r1.91 field.attach.inc
--- modules/field/field.attach.inc	17 Jun 2010 13:44:45 -0000	1.91
+++ modules/field/field.attach.inc	7 Jul 2010 23:42:34 -0000
@@ -1036,10 +1036,17 @@ function field_attach_delete_revision($e
 /**
  * Prepare field data prior to display.
  *
- * This function must be called before field_attach_view(). It lets field
- * types and formatters load additional data needed for display, and
- * therefore accepts an array of entities to allow query optimisation when
- * displaying lists of entities.
+ * This function lets field types and formatters load additional data
+ * needed for display that is not automatically loaded during
+ * field_attach_load(). It accepts an array of entities to allow query
+ * optimisation when displaying lists of entities.
+ *
+ * field_attach_prepare_view() and field_attach_view() are two halves
+ * of the same operation. It is safe to call
+ * field_attach_prepare_view() multiple times on the same entity
+ * before calling field_attach_view() on it, but calling any Field
+ * API operation on an entity between passing that entity to these two
+ * functions may yield incorrect results.
  *
  * @param $entity_type
  *   The type of $entities; e.g. 'node' or 'user'.
@@ -1077,8 +1084,12 @@ function field_attach_prepare_view($enti
  * Each field is displayed according to the display options specified in the
  * $instance definition for the given $view_mode.
  *
- * The entity must have run through field_attach_prepare_view() beforehands.
- * @see field_attach_prepare_view()
+ * field_attach_prepare_view() and field_attach_view() are two halves
+ * of the same operation. It is safe to call
+ * field_attach_prepare_view() multiple times on the same entity
+ * before calling field_attach_view() on it, but calling any Field
+ * API operation on an entity between passing that entity to these two
+ * functions may yield incorrect results.
  *
  * Sample structure:
  * @code