Document hook_wysiwyg_editor_settings_alter()

Some of these are pretty obvious but included for sake of completeness.

Basics

Function signature, brief info on arguments and return value.

Purpose

Why this hook exists and when it's called. Ex: "Exists to allow modules to alter the settings passed to an editor instance when it's attached to a field. Called after [possibly cached] profile settings have been retrieved from DB and just before settings are converted to a JSON object and passed to the client."

Audience

Who is this hook meant for? Any module integrating with Wysiwyg? Users needing to customize an editor configuration beyond what the current profile GUI can handle?

Powers

What can this hook do? Add settings? Remove settings? What settings are available for each editor. (Refer to the editors' official websites.) Are changes made by it cached? (No, meaning one can use it for dynamic changes.)

Limitations

What can't this hook do. Ex: "The values set by this hook must be of the PHP types Boolean, Integer/Float/Double, String[, NULL] or Arrays/Objects containing those. These will be converted to their corresponding JavaScript types before being passed to the client. Setting values of the JavaScript types Function-/Object-references, Regular Expressions or constants/variables cannot currently be set via this hook because they can't be automatically converted from PHP to JavaScript. @See http://api.drupal.org/api/function/drupal_to_js/6."

Considerations

Overriding settings that have GUI widgets on the profile pages will make the widgets useless. Other modules may be altering the same settings, check module weights.

Precedence

Ex. "The settings set in this hook will override any previous instance where the same setting has been defined, such as in a config.js file or similar, because they are passed directly to the editor instance. See editor's official website for more info."

Suggestions?

Yes, the strings $context['profile']->format and $context['profile']->editor should have that information.
The profile object is the same one as retrieved from wysiwyg_profile_load($format).

EDIT: Fixed syntax, thanks!

How about this?
I added the comments to avoid questions about why something like this won't work:

function hook_wysiwyg_editor_settings_alter(&$settings, $context) {
  if ($context['profile']->editor == 'tinymce') {
    $settings['fillEmptyBlocks'] = function ( element ) {
      // Expected to be executed as JavaScript.
      if ( element.attributes[ 'class' ].indexOf ( 'clear-both' ) != -1 )
        return false;
     }
   }
}

(Taken from the CKEditor config docs.)