Improve RenderArrayBase::getAccessResult() documentation

Problem/Motivation

If I understand correctly RenderArrayBase::getAccessResult() mimics how #access only has 2 states (allowed and not allowed). So it transforms forbidden access results to neutral.

The method description does not explain that so it could be confusing and could be a security problem if misused.

(This was originally logged as a private issue to the security team, but was cleared to be moved to the public queue.)

Steps to reproduce

  $renderArray = [
    '#markup' => 'foo',
    '#access' => AccessResult::forbidden('Nobody should be able to see this element.'),
  ];
  $renderArrayObject = RenderArray::alter($renderArray);

  // This is AccessResultForbidden.
  $renderArray['#access'];

  // But this is AccessResultNeutral
  $renderArrayObject->getAccessResult();

  // This is AccessResultForbidden.
  $renderArray['#access']->orIf(AccessResult::allowed());

  // This becomes AccessResultAllowed.
  $renderArrayObject->getAccessResult()->orIf(AccessResult::allowed());

Proposed resolution

Expand the method documentation to explain how it transforms the access result.

Remaining tasks

User interface changes

API changes

Data model changes