diff --git a/core/includes/pager.inc b/core/includes/pager.inc
index 7ce3407..2d102b9 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()
  */
@@ -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 controls 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 controls 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.
  */
@@ -279,32 +277,35 @@ function template_preprocess_pager(&$variables) {
 }
 
 /**
- * Adds the 'page' parameter to the query parameter array of a pager link.
+ * Adds the 'page' parameter to the URL query parameter array of a pager link.
+ *
+ * Since we can have multiple pagers on a single page, each pager has an index
+ * value assigned to it. If we have 5 pages on a single page, we could assign
+ * them the index numbers: 0, 1, 2, 3, 4. To indicate that the 3rd pager is on
+ * page 5, we would need to indicate this in the URL query, by having index 2
+ * have the value of 5. The URL query would then look like this: page=0,0,5.
+ * It's such an URL query that is generated through this function, taking all
+ * pagers on the page into account.
  *
  * @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
- *   The index of the target page in the pager array.
+ * @param int $page_number
+ *   The page number for the pager that should be set.
  *
  * @return array
  *   The altered $query parameter array.
- *
- * @todo Document the pager/element/index architecture and logic. It is not
- *   clear what is happening in this function as well as pager_load_array(),
- *   and whether this can be simplified in any way.
  */
-function pager_query_add_page(array $query, $element, $index) {
-  global $pager_page_array;
-
-  // Determine the first result to display on the linked page.
-  $page_new = pager_load_array($index, $element, $pager_page_array);
-
+function pager_query_add_page(array $query, $element, $page_number) {
+  // The general idea is to create an array with all the needed values and then
+  // use implode to convert it to a string of integers separated by comma. Get
+  // the default values from the request make sure other queries are maintained.
   $page = \Drupal::request()->query->get('page', '');
-  if ($new_page = implode(',', pager_load_array($page_new[$element], $element, explode(',', $page)))) {
+  if ($new_page = implode(',', pager_load_array($page_number, $element, explode(',', $page)))) {
     $query['page'] = $new_page;
   }
+
   // Merge the query parameters passed to this function with the parameters
   // from the current request. In case of collision, the parameters passed
   // into this function take precedence.
@@ -319,6 +320,17 @@ function pager_query_add_page(array $query, $element, $index) {
  *
  * Copies $old_array to $new_array and sets $new_array[$element] = $value
  * Fills in $new_array[0 .. $element - 1] = 0
+ *
+ * @param int $value
+ *   The value that will be set in the copied array returned by this function.
+ * @param int $element
+ *   The index that will have its value overridden in the copied array returned
+ *   by this function.
+ * @param array $old_array
+ *   Array that will be copied and modified.
+ *
+ * @return array
+ *   Copy of $old_array generated through the rule described above.
  */
 function pager_load_array($value, $element, $old_array) {
   $new_array = $old_array;
