diff --git a/core/core.services.yml b/core/core.services.yml
index 2c8b4a9..8a5092e 100644
--- a/core/core.services.yml
+++ b/core/core.services.yml
@@ -161,7 +161,7 @@ services:
   form_builder:
     class: Drupal\Core\Form\FormBuilder
     arguments: ['@form_validator', '@form_submitter', '@module_handler', '@keyvalue.expirable', '@event_dispatcher', '@request_stack', '@class_resolver', '@?csrf_token', '@?http_kernel']
-  form_builder.alter
+  form_builder.alter:
     class: Drupal\Core\Form\FormAlterSubscriber
     arguments: ['@module_handler', '@theme.manager']
     tags:
diff --git a/core/lib/Drupal/Core/Form/FormAlterEvent.php b/core/lib/Drupal/Core/Form/FormAlterEvent.php
index f397d34..d973461 100644
--- a/core/lib/Drupal/Core/Form/FormAlterEvent.php
+++ b/core/lib/Drupal/Core/Form/FormAlterEvent.php
@@ -10,26 +10,34 @@
 use Symfony\Component\EventDispatcher\Event;
 
 /**
- * @todo.
+ * Wraps a form and its current state for altering.
  */
 class FormAlterEvent extends Event {
 
   /**
+   * An associative array containing the structure of the form.
+   *
    * @var array
    */
   protected $form;
 
   /**
+   * The current state of the form.
+   *
    * @var \Drupal\Core\Form\FormStateInterface
    */
   protected $formState;
 
   /**
+   * The alter hooks to be invoked.
+   *
    * @var array
    */
   protected $hooks;
 
   /**
+   * The unique string identifying the form.
+   *
    * @var string
    */
   protected $formId;
@@ -46,36 +54,48 @@ class FormAlterEvent extends Event {
    * @param string $form_id
    *   The unique string identifying the desired form.
    */
-  function __construct($hooks, $form, FormStateInterface $form_state, $form_id) {
+  function __construct($hooks, &$form, FormStateInterface $form_state, $form_id) {
     $this->hooks = $hooks;
-    $this->form = $form;
+    $this->form = &$form;
     $this->formState = $form_state;
     $this->formId = $form_id;
   }
 
   /**
+   * Returns the form.
+   *
    * @return array
+   *   An associative array containing the structure of the form.
    */
   public function &getForm() {
     return $this->form;
   }
 
   /**
+   * Returns the form ID.
+   *
    * @return string
+   *   The unique string identifying the form.
    */
   public function getFormId() {
     return $this->formId;
   }
 
   /**
+   * Returns the form state.
+   *
    * @return \Drupal\Core\Form\FormStateInterface
+   *   The current state of the form.
    */
   public function getFormState() {
     return $this->formState;
   }
 
   /**
+   * Returns the array of alter hooks.
+   *
    * @return array
+   *   An array of the alter hooks to invoke.
    */
   public function getHooks() {
     return $this->hooks;
diff --git a/core/lib/Drupal/Core/Form/FormAlterSubscriber.php b/core/lib/Drupal/Core/Form/FormAlterSubscriber.php
index bafe2c9..1fd1bf8 100644
--- a/core/lib/Drupal/Core/Form/FormAlterSubscriber.php
+++ b/core/lib/Drupal/Core/Form/FormAlterSubscriber.php
@@ -61,6 +61,7 @@ public function onFormAlter(FormAlterEvent $event) {
    */
   public static function getSubscribedEvents() {
     $events[FormEvents::ALTER][] = 'onFormAlter';
+    return $events;
   }
 
 }
diff --git a/core/lib/Drupal/Core/Form/FormBuilder.php b/core/lib/Drupal/Core/Form/FormBuilder.php
index 56f2c19..82f0787 100644
--- a/core/lib/Drupal/Core/Form/FormBuilder.php
+++ b/core/lib/Drupal/Core/Form/FormBuilder.php
@@ -641,7 +641,20 @@ public function prepareForm($form_id, &$form, FormStateInterface &$form_state) {
         $form['#theme'][] = $form_state['build_info']['base_form_id'];
       }
     }
+    $this->alterForm($form_id, $form, $form_state);
+  }
 
+  /**
+   * Performs altering of the form.
+   *
+   * @param string $form_id
+   *   A unique string identifying the form.
+   * @param array $form
+   *   An associative array containing the structure of the form.
+   * @param \Drupal\Core\Form\FormStateInterface $form_state
+   *   The current state of the form.
+   */
+  protected function alterForm($form_id, &$form, FormStateInterface &$form_state) {
     // Invoke hook_form_alter(), hook_form_BASE_FORM_ID_alter(), and
     // hook_form_FORM_ID_alter() implementations.
     $hooks = array('form');
diff --git a/core/lib/Drupal/Core/Form/FormEvents.php b/core/lib/Drupal/Core/Form/FormEvents.php
index 632c317..4378f8c 100644
--- a/core/lib/Drupal/Core/Form/FormEvents.php
+++ b/core/lib/Drupal/Core/Form/FormEvents.php
@@ -8,10 +8,16 @@
 namespace Drupal\Core\Form;
 
 /**
- * @todo.
+ * Defines events for the form system.
  */
 final class FormEvents {
 
+  /**
+   * Name of event fired when altering a form.
+   *
+   * @see \Drupal\Core\Form\FormBuilder::alterForm()
+   * @see \Drupal\Core\Form\FormAlterEvent
+   */
   const ALTER = 'form_builder.alter';
 
 }