diff --git a/core/includes/common.inc b/core/includes/common.inc
index 19beefa..fb748d6 100644
--- a/core/includes/common.inc
+++ b/core/includes/common.inc
@@ -623,10 +623,36 @@ function drupal_merge_attached(array $a, array $b) {
  *   The structured array describing the data being rendered.
  *
  * @see drupal_render()
+ * @see hook_html_head_alter()
  * @see \Drupal\Core\Asset\AssetResolver
+ * @see \Drupal\Core\EventSubscriber\FinishResponseSubscriber
+ * @see \Symfony\Component\HttpKernel\KernelEvents::RESPONSE
  *
  * @throws LogicException
  *   When attaching something of a non-existing attachment type.
+ *
+ * @deprecated Will be removed before Drupal 8.2.0. Specify attached elements in
+ *   the render array from a controller, using ['#attached']. They will be
+ *   rendered into the response towards the end of the render process. For
+ *   example:
+ *   @code
+ *   $build['#attached'] = [
+ *     'library' => ['core/jquery']
+ *   ];
+ *   $build['#attached']['http_header'] = [
+ *     ['Content-Type', 'application/rss+xml; charset=utf-8'],
+ *   ];
+ *   return $build;
+ *   @endcode
+ *   For manipulating attached renderable items in non-controller applications,
+ *   there are three options:
+ *   - Set up an event subscriber for the
+ *     Symfony\Component\HttpKernel\KernelEvents::RESPONSE event. See
+ *     Drupal\Core\EventSubscriber\FinishResponseSubscriber for an example.
+ *   - Specify $variables['#attached'] in theme preprocess functions.
+ *   - Use hook_html_head_alter() to change HTML head elements.
+ *   To render attachments without a controller, use the
+ *   'bare_html_page_renderer' service.
  */
 function drupal_process_attached(array $elements) {
   // Asset attachments are handled by \Drupal\Core\Asset\AssetResolver.