From 16093cc1462d4397b9d43360ff7d93091a48975b Mon Sep 17 00:00:00 2001
From: Alex Pott <alex.a.pott@googlemail.com>
Date: Fri, 17 Jun 2016 11:47:38 +0100
Subject: [PATCH] Issue #2674508 by Mile23, tim.plunkett: Improve docs for how
 to properly add container injection into a class that extends FormBase

---
 core/lib/Drupal/Core/Form/FormBase.php | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/core/lib/Drupal/Core/Form/FormBase.php b/core/lib/Drupal/Core/Form/FormBase.php
index c33f2a16784..4a020dc2aec 100644
--- a/core/lib/Drupal/Core/Form/FormBase.php
+++ b/core/lib/Drupal/Core/Form/FormBase.php
@@ -15,7 +15,29 @@ use Symfony\Component\HttpFoundation\RequestStack;
 /**
  * Provides a base class for forms.
  *
+ * This class exists as a mid-point between dependency injection through
+ * ContainerInjectionInterface, and a less-structured use of traits which
+ * default to using the \Drupal accessor for service discovery.
+ *
+ * To properly inject services, override create() and use the setters provided
+ * by the traits to inject the needed services.
+ *
+ * @code
+ * public static function create($container) {
+ *   $form = new static();
+ *   // In this example we only need string translation so we use the
+ *   // setStringTranslation() method provided by StringTranslationTrait.
+ *   $form->setStringTranslation($container->get('string_translation'));
+ *   return $form;
+ * }
+ * @endcode
+ *
+ * Alternately, do not use FormBase. A class can implement FormInterface, use
+ * the traits it needs, and inject services from the container as required.
+ *
  * @ingroup form_api
+ *
+ * @see \Drupal\Core\DependencyInjection\ContainerInjectionInterface
  */
 abstract class FormBase implements FormInterface, ContainerInjectionInterface {