diff --git a/core/includes/bootstrap.inc b/core/includes/bootstrap.inc
index 2294d47..d2eef84 100644
--- a/core/includes/bootstrap.inc
+++ b/core/includes/bootstrap.inc
@@ -865,6 +865,10 @@ function drupal_classloader_register($name, $path) {
  * @return
  *   Returns a variable by reference.
  *
+ * @deprecated in Drupal 8.2.x, will be removed before Drupal 9.0.0. Do not use
+ *   static PHP variables. If in-memory caching is required, use a non-static
+ *   property on a long-lived object such as a service.
+ *
  * @see drupal_static_reset()
  */
 function &drupal_static($name, $default_value = NULL, $reset = FALSE) {
@@ -907,6 +911,11 @@ function &drupal_static($name, $default_value = NULL, $reset = FALSE) {
  *   Name of the static variable to reset. Omit to reset all variables.
  *   Resetting all variables should only be used, for example, for running
  *   unit tests with a clean environment.
+ *
+ * @deprecated in Drupal 8.2.x, will be removed before Drupal 9.0.0. Do not use
+ *   static PHP variables.
+ *
+ * @see drupal_static()
  */
 function drupal_static_reset($name = NULL) {
   drupal_static($name, NULL, TRUE);