diff --git a/core/includes/pager.inc b/core/includes/pager.inc
index 7b106ea..dfffd06 100644
--- a/core/includes/pager.inc
+++ b/core/includes/pager.inc
@@ -11,18 +11,18 @@
 /**
  * Returns the current page being requested for display within a pager.
  *
- * @param $element
- *  An optional integer to distinguish between multiple pagers on one page.
+ * @param int $element
+ *   An optional integer to distinguish between multiple pagers on one page.
  *
- * @return
- *  The number of the current requested page, within the pager represented by
- *  $element. This is determined from the URL query parameter
- *  \Drupal::request()->query->get('page'), or 0 by default. Note that this
- *  number may differ from the actual page being displayed. For example, if a
- *  search for "example text" brings up three pages of results, but a users
- *  visits search/node/example+text?page=10, this function will return 10, even
- *  though the default pager implementation adjusts for this and still displays
- * the third page of search results at that URL.
+ * @return int
+ *   The number of the current requested page, within the pager represented by
+ *   $element. This is determined from the URL query parameter
+ *   \Drupal::request()->query->get('page'), or 0 by default. Note that this
+ *   number may differ from the actual page being displayed. For example, if a
+ *   search for "example text" brings up three pages of results, but a user
+ *   visits search/node/example+text?page=10, this function will return 10,
+ *   even though the default pager implementation adjusts for this and still
+ *   displays the third page of search results at that URL.
  *
  * @see pager_default_initialize()
  */
@@ -36,11 +36,11 @@ function pager_find_page($element = 0) {
 }
 
 /**
- * Initializes a pager for _theme('pager').
+ * Initializes a pager.
  *
- * This function sets up the necessary global variables so that future calls
- * to _theme('pager') will render a pager that correctly corresponds to the
- * items being displayed.
+ * This function sets up the necessary global variables so that the render
+ * system will correctly process #type 'pager' render arrays to output pagers
+ * that correspond to the items being displayed.
  *
  * If the items being displayed result from a database query performed using
  * Drupal's database API, and if you have control over the construction of the
@@ -55,7 +55,7 @@ function pager_find_page($element = 0) {
  * However, if you are using a different method for generating the items to be
  * paged through, then you should call this function in preparation.
  *
- * The following example shows how this function can be used in a page callback
+ * The following example shows how this function can be used in a controller
  * that invokes an external datastore with an SQL-like syntax:
  * @code
  *   // First find the total number of items and initialize the pager.
@@ -64,21 +64,21 @@ function pager_find_page($element = 0) {
  *   $num_per_page = \Drupal::config('mymodule.settings')->get('num_per_page');
  *   $page = pager_default_initialize($total, $num_per_page);
  *
- *   // Next, retrieve and display the items for the current page.
+ *   // Next, retrieve the items for the current page and put them into a
+ *   // render array.
  *   $offset = $num_per_page * $page;
  *   $result = mymodule_select("SELECT * FROM data " . $where . " LIMIT %d, %d", $offset, $num_per_page)->fetchAll();
- *   $output = drupal_render(
+ *   $render = [[
  *     '#theme' => 'mymodule_results',
  *     '#result' => $result,
- *   );
+ *   ]];
  *
- *   // Finally, display the pager controls, and return.
- *   $pager = array('#type' => 'pager');
- *   $output .= drupal_render($pager);
- *   return $output;
+ *   // Finally, add the pager to the render array, and return.
+ *   $render[] = ['#type' => 'pager'];
+ *   return $render;
  * @endcode
  *
- * A second example involves a page callback that invokes an external search
+ * A second example involves a controller that invokes an external search
  * service where the total number of matching results is provided as part of
  * the returned set (so that we do not need a separate query in order to obtain
  * this information). Here, we call pager_find_page() to calculate the desired
@@ -96,28 +96,26 @@ function pager_find_page($element = 0) {
  *   // Now that we have the total number of results, initialize the pager.
  *   pager_default_initialize($result->total, $num_per_page);
  *
- *   // Display the search results.
- *   $search_results = array(
+ *   // Create a render array with the search results.
+ *   $render = [[
  *     '#theme' => 'search_results',
  *     '#results' => $result->data,
  *     '#type' => 'remote',
- *   );
- *   $output = drupal_render($search_results);
+ *   ]];
  *
- *   // Finally, display the pager controls, and return.
- *   $pager = array('#type' => 'pager');
- *   $output .= drupal_render($pager);
- *   return $output;
+ *   // Finally, add the pager to the render array, and return.
+ *   $render[] = ['#type' => 'pager'];
+ *   return $render;
  * @endcode
  *
- * @param $total
- *  The total number of items to be paged.
- * @param $limit
- *  The number of items the calling code will display per page.
- * @param $element
- *  An optional integer to distinguish between multiple pagers on one page.
+ * @param int $total
+ *   The total number of items to be paged.
+ * @param int $limit
+ *   The number of items the calling code will display per page.
+ * @param int $element
+ *   An optional integer to distinguish between multiple pagers on one page.
  *
- * @return
+ * @return int
  *   The number of the current page, within the pager represented by $element.
  *   This is determined from the URL query parameter
  *   \Drupal::request()->query->get('page), or 0 by default. However, if a page
@@ -141,7 +139,7 @@ function pager_default_initialize($total, $limit, $element = 0) {
 /**
  * Compose a URL query parameter array for pager links.
  *
- * @return
+ * @return array
  *   A URL query parameter array that consists of all components of the current
  *   page request except for those pertaining to paging.
  */
@@ -288,15 +286,24 @@ function template_preprocess_pager(&$variables) {
  * Get the query parameter array of a pager link.
  *
  * Adds or adjusts the 'page' parameter to make sure that, following the link,
- * the requested $page for the given $element is displayed.
+ * the requested page for the given element is displayed.
  * The 'page' parameter is a comma-delimited string, where each value is the
  * target page for the corresponding pager $element.
+ * Since we can have multiple pagers on a single page, each pager has an
+ * element value assigned to it. If we have 5 pagers on a single page, we could
+ * assign them the element numbers: 0, 1, 2, 3, 4. To indicate that the 3rd
+ * pager needs to jump to page page 5 (note that in the pager query, the page
+ * numbers are zero-indexed, i.e. page at index 5 means that the pager will
+ * display page 6 to the users), we would need to indicate this in the URL
+ * query, by having element 2 have the index of 5. The URL query would then
+ * look like this, supposing all other pagers are on page index 0:
+ * ?page=0,0,5,0,0.
  *
  * @param array $query
  *   An associative array of query parameters to add to.
- * @param integer $element
+ * @param int $element
  *   An integer to distinguish between multiple pagers on one page.
- * @param integer $index
+ * @param int $index
  *   The index of the target page, for the given element, in the pager array.
  *
  * @return array
