hook_field_formatter_settings_form() should mention it only works with a corresponding summary

OK, this needs to be verified in the code and then added to the docs.

OK, I'm looking at the code. The place where the Display settings page is built is:
https://api.drupal.org/api/drupal/modules!field_ui!field_ui.admin.inc/fu...

What you're saying is definitely true. The display form does this, near the bottom:

    // Display a summary of the current formatter settings.
      $summary = module_invoke($formatter['module'], 'field_formatter_settings_summary', $field, $instance, $view_mode);
      $table[$name]['settings_summary'] = array();
      $table[$name]['settings_edit'] = array();
      if ($summary) {
        // (put up the edit button and a summary of the settings)
      }

So, it does look like we should edit hook_field_formatter_settings_form() to say that if you have a settings form, you also need to implement hook_field_formatter_settings_summary() and make sure it returns a value that does not evaluate to FALSE (a non-empty string). The docs for https://api.drupal.org/api/drupal/modules!field_ui!field_ui.api.php/func... already say this, but I definitely agree it should be mentioned on the settings form hook too.

These two hooks should also be in the group/topic field_formatter, not field_types as they are now. (While we're at it, is it too out of scope to fix hook_field_widget_settings_form to be in group/topic field_widget instead of field_types too, in the same file?)

I am updating the documentation hook_field_formatter_settings_form().

Please review the patch. The documentation for hook_field_formatter_settings_form() has been updated to mention that it needs hook_field_formatter_settings_summary() implementation to get invoked.

Thanks!

Could we make the wording a little better though? It seems awkward to me.

Maybe:

This hook is not invoked unless hook_field_formatter_settings_summary() returns a non-empty value.

What do you think?

I like the last option in #7. Can we get a new patch? Thanks!

Sure, I will update the wordings.

Please review the new patch. Thanks!

I am new to d.o contribution, so just wondering if I need to provide an advanced patch using "git format-patch", or just the "git diff" is enough for drupal core.

Thanks @joachim.

Thanks!

10: doc_update_for_hook_field_formatter_settings_form_requires_summary_hook-2268947-10.patch queued for re-testing.

Thanks again! Committed to 7.x.

Thank you, was my first commit so far :)

Congratulations sachin_s!