flag_get_FOO_counts() API functions do not have their static caches reset when (un)flagging

We can use the same change record for this as #2154251: Flag status incorrect when flagging another flag as a reaction to unflagging (Javascript), https://drupal.org/node/2210055

Got a local branch for this about ready to do; will make patch soon.

Includes docs for all the flag_*_count() functions.

Follow-up: #2212727: add detail on flag counts to Rules actions.

This causes a lot of changes to the API functions. Here's the data that the test gathers from them -- the keys are the names of the API functions, the values the data they return when called during the hook invocation.

During a flagging, hook_entity_insert() and hook_flag_flag():

// Before:
array (
  'flag_get_entity_flags' => 
  array (
  ),
  'flag_get_user_flags' => 
  array (
  ),
  'flag_get_counts' => 
  array (
  ),
  'flag_get_flag_counts' => '0',
  'flag_get_entity_flag_counts' => '0',
  'flag_get_user_flag_counts' => '0',
)

// After:
array (
  'flag_get_entity_flags' => 
  array (
    2 => FLAGGING
  ),
  'flag_get_user_flags' => 
  array (
    'flag_hook_test_flag' => FLAGGING
  ),
  'flag_get_counts' => 
  array (
    'flag_hook_test_flag' => '1',
  ),
  'flag_get_flag_counts' => '1',
  'flag_get_entity_flag_counts' => '1',
  'flag_get_user_flag_counts' => '1',
)

During an unflagging, hook_flag_unflag(), hook_entity_delete():

// Before:
array (
  'flag_get_entity_flags' => 
  array (
    2 => FLAGGING
  ),
  'flag_get_user_flags' => 
  array (
    'flag_hook_test_flag' => FLAGGING
  ),
  'flag_get_counts' => 
  array (
  ),
  'flag_get_flag_counts' => '0',
  'flag_get_entity_flag_counts' => '1',
  'flag_get_user_flag_counts' => '1',
)

// After:
array (
  'flag_get_entity_flags' => 
  array (
    2 => FLAGGING
  ),
  'flag_get_user_flags' => 
  array (
    'flag_hook_test_flag' => FLAGGING
  ),
  'flag_get_counts' => 
  array (
  ),
  'flag_get_flag_counts' => '0',
  'flag_get_entity_flag_counts' => '1',
  'flag_get_user_flag_counts' => '1',
)

Note that not all flag_get_foo_counts() functions behave the same way -- some don't get updated data in an unflagging because they query the flagging table rather than flag_counts.

Issue #2208847 by joachim: Fixed static caches of Flag API not getting reset when flagging and unflagging.

Thanks for the review!

Off to update the change record now.

Not pushed this yet, as getting myself tied in knots with the CR.

Above, I pasted that during unflagging, the old behaviour was:

  'flag_get_entity_flag_counts' => '1',
  'flag_get_user_flag_counts' => '1',

but in my notes for the CR, I have 0s for those. That would be a regression! Need to do more investigating...

Ok, panic over. My notes were wrong; the comment above has the correct data.

https://drupal.org/node/2210055 updated.