FormBuild docs

Closes #2776661

core/lib/Drupal/Core/Form/FormBuilder.php

@@ -602,16 +602,16 @@ public function processForm($form_id, &$form, FormStateInterface &$form_state) {
         return;
       }
 
-      // If $form_state->isRebuilding() has been set and input has been
+      // If $form_state->setRebuild(TRUE) was called and input has been
       // processed without validation errors, we are in a multi-step workflow
-      // that is not yet complete. A new $form needs to be constructed based on
-      // the changes made to $form_state during this request. Normally, a submit
-      // handler sets $form_state->isRebuilding() if a fully executed form
-      // requires another step. However, for forms that have not been fully
-      // executed (e.g., Ajax submissions triggered by non-buttons), there is no
-      // submit handler to set $form_state->isRebuilding(). It would not make
-      // sense to redisplay the identical form without an error for the user to
-      // correct, so we also rebuild error-free non-executed forms, regardless
+      // that is not yet complete. A new $form needs to be constructed based
+      // on the changes made to $form_state during this request.
+      //
+      // Typically, a submit handler calls $form_state->setRebuild(TRUE) when
+      // a fully executed form requires another step. However, for forms that
+      // have not been fully executed (e.g., AJAX submissions triggered by
+      // non-buttons), there is no submit handler to call setRebuild(). In
+      // that case, we also rebuild error-free, non-executed forms, regardless
       // of $form_state->isRebuilding().
       // @todo Simplify this logic; considering Ajax and non-HTML front-ends,
       //   along with element-level #submit properties, it makes no sense to