Assert action is 'flag' or 'unflag'

This is a side issue, in response

https://www.drupal.org/node/2584647#comment-11577277

#2

Also, per documentation, action must be one of those values, so why check it, should be checked earlier and an exception thrown or something?

$action must be 'flag' or 'unflag'

Some of the specialist knowledge floating around in the back of my head is that the code has been carefully constructed - so that if the $action get corrupted with a value like "socks" say then the action 'flag' is assumed to be the default value 'flag'.

and by specialist knowledge --- I mean a code smell.

this is encoded in

Drupal\flag\ActionLink\ActionLinkTypeBase::buildLink()

    if ($action === 'unflag') {
      $render['#title'] = $flag->getUnflagShortText();
      $render['#attributes']['title'] = $flag->getUnflagLongText();
      $render['#action'] = 'unflag';
    }
    else {
      $render['#title'] = $flag->getFlagShortText();
      $render['#attributes']['title'] = $flag->getFlagLongText();
      $render['#action'] = 'flag';
    }

this is the subtlety in 'unflag' coming before flag.

I have had to learn this to hard way - I have seen more that a few comments in separate issue suggesting this is wonky/confusing.

I am happy for production code to default to flag - there is no need to throw an exception -
to my mind this is the case for an assert - something that will never hit production.

If other want to update specific documentation or add addition asserts then -- that will come up in review :)