Problem/Motivation

I looked at the documentation for in the pager.inc and saw several problems with it. It doesn't follow the standards and a lot of the documentation is really outdated. Example code is using deprecated functions and callbacks is referenced, which isn't used anymore.

Proposed resolution

We should go through the file and clean up all of the documentation and get it up to speed.

Remaining tasks

Do it.

User interface changes

None

API changes

None

Data model changes

None

Beta phase evaluation

Reference: https://www.drupal.org/core/beta-changes
Issue category Task because it is something that just needs to be done
Issue priority Normal
Unfrozen changes Unfrozen because it only changes documentation.
Prioritized changes Improve documentation

Comments

cilefen’s picture

Title: The documentation in core/includes/pager.inc is outdate » The documentation in core/includes/pager.inc is outdated
cilefen’s picture

Issue summary: View changes

This could be considered a documentation bug depending on how bad it is.

googletorp’s picture

Status: Active » Needs review
StatusFileSize
new6.88 KB

Besides the documentation cleanup, I also removed the @todo in the file, and made it more clear what is going on in pager_query_add_page. This resulted in some minor code clean up as well.

pager_query_add_page did a weird thing, that didn't really make sense, which might have been what spawned the todo.

Before the code looked like this:

global $pager_page_array;
$page_new = pager_load_array($index, $element, $pager_page_array);
// $page_new[$element] is used
// $page_new[$element] === $index

It seems strange to construct $page_new and not use it for anything, so the above code could be removed by replacing $page_new[$element] with $index.

I don't know if this is scope creep, but since still is heavily tied with the actual documentation of this, I think it's ok.

jhodgdon’s picture

Status: Needs review » Needs work

Hmmm.... Well if you are going to change code, this is no longer a Documentation issue. Either change the issue title, summary, and component to indicate it is not just Documentation, or limit your changes to documentation. My preference would be to keep this as Documentation and file a separate issue on the code changes... the code changes here look questionable to me too -- that global array is used in the theming somewhere, isn't it? It always was before.

Anyway... looking at the patch, there are some problems in the docs too:

  1. +++ b/core/includes/pager.inc
    @@ -11,10 +11,10 @@
      *  An optional integer to distinguish between multiple pagers on one page.
    

    integer -> int

    See
    https://www.drupal.org/node/1354#types

  2. +++ b/core/includes/pager.inc
    @@ -11,10 +11,10 @@
    + * @return integer
    

    same here

  3. +++ b/core/includes/pager.inc
    @@ -96,28 +96,26 @@ function pager_find_page($element = 0) {
    - * @param $total
    + * @param integer $total
      *  The total number of items to be paged.
    - * @param $limit
    + * @param integer $limit
      *  The number of items the calling code will display per page.
    - * @param $element
    + * @param integer $element
      *  An optional integer to distinguish between multiple pagers on one page.
      *
    - * @return
    + * @return integer
      *   The number of the current page, within the pager represented by $element.
    

    Also if we are fixing the docs here, the indentation of the parameter docs is only 1 character instead of 2, want to fix that too?

  4. +++ b/core/includes/pager.inc
    @@ -96,28 +96,26 @@ function pager_find_page($element = 0) {
    + * @param integer $total
    

    integer -> int

  5. +++ b/core/includes/pager.inc
    @@ -96,28 +96,26 @@ function pager_find_page($element = 0) {
    + * @param integer $limit
    

    same

  6. +++ b/core/includes/pager.inc
    @@ -96,28 +96,26 @@ function pager_find_page($element = 0) {
    + * @param integer $element
    

    same

  7. +++ b/core/includes/pager.inc
    @@ -281,6 +279,14 @@ function template_preprocess_pager(&$variables) {
    + * Since we can have multiple pager 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 indecate, 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 query would then look like this: page=0,0,5. It's
    + * such quries that is generated through this function, taking all pagers on
    + * the page into account.
    + *
    

    Could this be rewritten to make it very clear the difference between a database query (which this is related to) and URL query parameters? And it's a bit awkward writing...

    Also, other typos:
    "multiple pager" => "multiple pagers"
    indecate -> indicate
    no comma after "indicate" on 3rd line.
    quries -> queries
    that is generated -> that are generated

  8. +++ b/core/includes/pager.inc
    @@ -290,21 +296,16 @@ function template_preprocess_pager(&$variables) {
    +  // use implode to convert it to a string of integers seperated by comma. Get
    

    separated -> separated

  9. +++ b/core/includes/pager.inc
    @@ -319,6 +320,16 @@ function pager_query_add_page(array $query, $element, $index) {
    + * @param integer $value
    

    integer -> int

    same in the next param

  10. +++ b/core/includes/pager.inc
    @@ -319,6 +320,16 @@ function pager_query_add_page(array $query, $element, $index) {
    + *   The value to for the $element index in the array to be returned.
    

    This is garbled.

  11. +++ b/core/includes/pager.inc
    @@ -319,6 +320,16 @@ function pager_query_add_page(array $query, $element, $index) {
    + *   The index that should have it value set to the value of $value.
    

    Not sure what this means.

  12. +++ b/core/includes/pager.inc
    @@ -319,6 +320,16 @@ function pager_query_add_page(array $query, $element, $index) {
    + *   The array the is the base for the array to be generated.
    

    This is also garbled.

googletorp’s picture

Component: documentation » other
Issue summary: View changes
Status: Needs work » Needs review
StatusFileSize
new8.83 KB
new5.88 KB

Thanks for the review jhodgdon, I'll like to keep the code changes in here, since they are needed in order to make the documetation and code simple and easy to understand.

I've updated the issue to reflect this, it wasn't my original goal with this task, but I felt it became needed.

If you look through the current code, you can see that the global array isn't used in any way and just make the code more garbled and complex.

What the old code did was this:

1. Fetch a global array.
2. Make a copy of the array (the array itself isn't changed)
3. Set a value in the copied array and possible add a lot of 0 values
4. Use the value set in #3 in a function call.

The new code is just using the value same as before, but skips fetching the array, copying it and modifying the copy.

I guess at some point the global value was used as a reference, but that isn't the case anymore, so the code is completely unneeded.

If you feel strongly about doing the code change in a separate issue, we can do that as well.

googletorp’s picture

Oh, and I've addressed all the issues raised by jhodgdon's review in #4

jhodgdon’s picture

Component: other » base system
Status: Needs review » Needs work

Changing component... this maybe should actually be in "database system" but I think "base" is OK. You'll need to get someone else to review the code changes.

Meanwhile I've reviewed the new docs -- they look better! A few more small suggestions (one is in preexisting docs that you just rewrapped, but the rest are in new docs I think).

  1. +++ b/core/includes/pager.inc
    @@ -11,18 +11,18 @@
    + *   search for "example text" brings up three pages of results, but a users
    

    typo: users -> user

  2. +++ b/core/includes/pager.inc
    @@ -166,7 +164,7 @@ function pager_get_query_parameters() {
    - *     - #element: An optional integer to distinguish between multiple pagers on
    + *     - #element: An optional int to distinguish between multiple pagers on
      *       one page.
    

    In this case, I would leave the word "integer" as it was. This is just English text, where "integer" is a word and "int" isn't. In @param/@return/@var types is where we want to use "int" to indicate an integer value.

  3. +++ b/core/includes/pager.inc
    @@ -279,32 +277,35 @@ function template_preprocess_pager(&$variables) {
    + * Adds the 'page' parameter to the url query parameter array of a pager link.
    

    url => URL

  4. +++ b/core/includes/pager.inc
    @@ -279,32 +277,35 @@ function template_preprocess_pager(&$variables) {
    + * It's such an url query that is generated through this function, taking all
    

    an url => a URL

  5. +++ b/core/includes/pager.inc
    @@ -279,32 +277,35 @@ function template_preprocess_pager(&$variables) {
    + * @param int $index
      *   The index of the target page in the pager array.
      *
      * @return array
    

    Is this parameter actually the page number? If so, maybe it should say that?

  6. +++ b/core/includes/pager.inc
    @@ -319,6 +320,17 @@ function pager_query_add_page(array $query, $element, $index) {
    + *   The value which will be set in the copied array returned by this function.
    

    which -> that

  7. +++ b/core/includes/pager.inc
    @@ -319,6 +320,17 @@ function pager_query_add_page(array $query, $element, $index) {
    + *   The index which will have it's value overridden in the copied array
    + *   returned by this function.
    

    which -> that
    it's -> its

  8. +++ b/core/includes/pager.inc
    @@ -319,6 +320,17 @@ function pager_query_add_page(array $query, $element, $index) {
    + *   Array which will be copied and modified.
    

    which -> that

jhodgdon’s picture

Title: The documentation in core/includes/pager.inc is outdated » Fix up docs and code in core/includes/pager.inc
googletorp’s picture

Status: Needs work » Needs review
StatusFileSize
new8.46 KB
new3.99 KB

Thanks for the additional review. I fixed the new grammar/spelling issues.

Also renamed $index to $page_no and updated the documentation. This variable is the page number for the selected pager. Thinking of arrays, it's the value and not the index of the array, which makes this a bit confusing to understand. I think this makes the code more clear, even though it's not the best part of Drupal 8.

jhodgdon’s picture

Our coding standards say not to abbreviate variable names, so $page_no is not a good name. Probably just use $page.

googletorp’s picture

StatusFileSize
new8.47 KB
new1.19 KB

Renamed $page_no to $page_number, since $page was already in use a bit further down.

jhodgdon’s picture

The docs look good to me now, except one small typo:

+++ b/core/includes/pager.inc
@@ -279,32 +277,35 @@ function template_preprocess_pager(&$variables) {
+ * It's such an URL query that is generated through this function, taking all

an URL -> a URL

I am still suspicious of the code changes, however, and you'll need to find someone else to review those.

andileco’s picture

Patch with the typo corrected.

mikeker’s picture

mondrake’s picture

Component: base system » documentation
Issue tags: -Documentation
StatusFileSize
new3.93 KB
new7.47 KB

Rerolled after #2539472: Pager "first" and "previous" links have incorrect URLs. pager_load_array() was removed in that patch, so bits related to that are no longer needed.
Also, removed references to _theme('pager') and made related comments to the render system, and fixed some lines exceeding 80-chars.

The patch here no longer touches code, so setting back to 'documentation'.

Interdiff from after merging.

mondrake’s picture

Issue summary: View changes

Updated IS and Beta Evaluation to remove references to code changes that no longer apply.

googletorp’s picture

Title: Fix up docs and code in core/includes/pager.inc » Fix up docs in core/includes/pager.inc
Related issues: -#2539472: Pager "first" and "previous" links have incorrect URLs

@jhodgdon This is now a pure documentation cleanup. You reviewed this earlier so is it fine to RTBC?

Status: Needs review » Needs work

The last submitted patch, 15: 2530296-15.patch, failed testing.

Status: Needs work » Needs review

mondrake queued 15: 2530296-15.patch for re-testing.

jhodgdon’s picture

Status: Needs review » Needs work

It's mostly good... maybe I wasn't too careful in my last review. But this block has some problems:

+++ b/core/includes/pager.inc
@@ -288,15 +286,24 @@ function template_preprocess_pager(&$variables) {
+ * 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.

a) As this is all one paragraph, it would be preferable to have it all wrapped at nearly-80-character lines. As it is, it's a bit choppy, which in general is distracting to readers.

b) I am also not really fond of the text starting with "Since..." in this block. I would suggest it could be much more concise... maybe something like:

For instance, if we have 5 pagers on a single page, with the 3rd one on page 6 and all others on page 1, the URL query would look like this: ?page=0,0,5,0,0 (page numbering starts at zero).

Really, I think this is much clearer and gets the point across.... thoughts? Remember, we're writing documentation for programmers. We don't have to be pedantic or explain what "starts at zero" means in great detail.

mikeker’s picture

+++ b/core/includes/pager.inc
@@ -288,15 +286,24 @@ function template_preprocess_pager(&$variables) {
  * 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

This is confusion since there is no $page parameter. It is referring to the 'page' query string argument.

I'll work on rewriting that doc block.

jhodgdon’s picture

Regarding #21, ... The correct term for something like ?page= or &page= in a URL is a "query parameter"... so it is a "parameter", just not a "function parameter". So in that last line where it says "The 'page' parameter is...", that is correct, but it should probably say "The 'page' URL query parameter..." to clarify.

mondrake’s picture

Status: Needs work » Needs review
Issue tags: +rc eligible
StatusFileSize
new7.52 KB
new2.88 KB

Tried to address feedback from #20 to #22.

@mikeker - I hope I did not step on your toes :)

jhodgdon’s picture

Status: Needs review » Needs work

Yeah! This is very very close. I think we can make it even better with a few small changes though:

  1. +++ b/core/includes/pager.inc
    @@ -10,18 +10,18 @@
    + *   An optional integer to distinguish between multiple pagers on one page.
    

    So, we actually have a slightly different standard syntax for indicating an optional parameter. It would say:

    @param int foo
      (optional) An integer to distinguish....
    

    Let's do that here. Sorry for not bringing that up earlier.

  2. +++ b/core/includes/pager.inc
    @@ -95,28 +96,27 @@ function pager_find_page($element = 0) {
    + *   An optional integer to distinguish between multiple pagers on one page.
    

    We should do the same as above here with (optional)

  3. +++ b/core/includes/pager.inc
    @@ -284,18 +284,24 @@ function template_preprocess_pager(&$variables) {
    + * Adds or adjusts the 'page' URL query parameter to make sure that, following
    + * the link, the paged content indicated by $index for the given pager $element
    + * gets displayed.
    

    This looks pretty good... but I'm not sure about "indicated by $index" or "following the link" -- the wording still seems a bit awkward and confusing.

    Would this be better wording:

    Adds to or adjusts the 'page' URL query parameter so that if you follow the link, you'll get page $index for pager $element on the page.

  4. +++ b/core/includes/pager.inc
    @@ -284,18 +284,24 @@ function template_preprocess_pager(&$variables) {
      *   An associative array of query parameters to add to.
    

    Can we say "URL query parameters" instead of just "query parameters" here too?

  5. +++ b/core/includes/pager.inc
    @@ -284,18 +284,24 @@ function template_preprocess_pager(&$variables) {
    + * Get the URL query parameter array of a pager link.
    

    Get => Gets

Thanks!

snehi’s picture

Status: Needs work » Needs review
StatusFileSize
new7.55 KB
new1.99 KB

Done.

jhodgdon’s picture

Status: Needs review » Needs work
+++ b/core/includes/pager.inc
@@ -284,18 +284,23 @@ function template_preprocess_pager(&$variables) {
+ * link, you'll get page $index for pager $element on the page. ¶

There is a blank space at the end of this line.

You should be able to configure your code editor to highlight or remove end of line spaces. Please do so! :)

The rest looks fine, thanks!

snehi’s picture

Status: Needs work » Needs review
StatusFileSize
new7.55 KB
new652 bytes

Done.

jhodgdon’s picture

Status: Needs review » Reviewed & tested by the community

Great, thanks!

  • xjm committed 418d6f9 on 8.0.x
    Issue #2530296 by googletorp, mondrake, snehi, andile2012, jhodgdon,...
xjm’s picture

Status: Reviewed & tested by the community » Fixed

Great work on this! In addition to adding data typing, fixing formatting, and removing references to several deprecated or removed APIs, this makes the documentation easier to understand as well. I reviewed the patch with git diff --color-words to inspect all the changes.

I didn't test the code example for pager_default_initialize(), nor did I find any examples in core that do that, but it's at least not totally wrong any more in terms of the routing and render systems.

So committed and pushed to 8.0.x. Thanks!

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.