Weight not a property of a field instance, so doc shouldn't say it is

Hm. Really? I think that the instance has a weight also for purposes of displaying the fields on (for instance) the node/# page, which has nothing to do with widgets?

Hm. It looks to me as though _field_write_instance (see link above in original issue report) is using both the widget's weight and the display mode formatter's weight:

if (!isset($instance['widget']['weight'])) {
    $max_weight = field_info_max_weight($instance['entity_type'], $instance['bundle'], 'form');
    $instance['widget']['weight'] = isset($max_weight) ? $max_weight + 1 : 0;
  }
...
   if (!isset($display['weight'])) {
      $max_weight = field_info_max_weight($instance['entity_type'], $instance['bundle'], $view_mode);
      $display['weight'] = isset($max_weight) ? $max_weight + 1 : 0;
    }

So it does look like weight is not a property of the instance itself, and the doc should just have the weight item removed from it.

Should be fixed in 8.x first then 7.x

Here's a patch against 8.x that simply removes the weight property from the doc for field_create_instance().

Thanks jhedstrom! Patch looks good for d8 and d7.

Yup, remnant of the time when fields where not reorderable view mode by view mode, i.e. weight was for the instance as a whole. That one occurrence got overlooked.

Confirming rtbc.

Committed to 7.x and 8.x. Thanks.