Closed (fixed)
Project:
Drupal core
Version:
8.0.x-dev
Component:
documentation
Priority:
Normal
Category:
Task
Assigned:
Unassigned
Issue tags:
Reporter:
Created:
9 Jul 2015 at 19:45 UTC
Updated:
8 Nov 2015 at 18:14 UTC
Jump to comment: Most recent, Most recent file
Comments
Comment #1
cilefen commentedComment #2
cilefen commentedThis could be considered a documentation bug depending on how bad it is.
Comment #3
googletorp commentedBesides 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:
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.
Comment #4
jhodgdonHmmm.... 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:
integer -> int
See
https://www.drupal.org/node/1354#types
same here
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?
integer -> int
same
same
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
separated -> separated
integer -> int
same in the next param
This is garbled.
Not sure what this means.
This is also garbled.
Comment #5
googletorp commentedThanks 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.
Comment #6
googletorp commentedOh, and I've addressed all the issues raised by jhodgdon's review in #4
Comment #7
jhodgdonChanging 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).
typo: users -> user
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.
url => URL
an url => a URL
Is this parameter actually the page number? If so, maybe it should say that?
which -> that
which -> that
it's -> its
which -> that
Comment #8
jhodgdonComment #9
googletorp commentedThanks 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.
Comment #10
jhodgdonOur coding standards say not to abbreviate variable names, so $page_no is not a good name. Probably just use $page.
Comment #11
googletorp commentedRenamed $page_no to $page_number, since $page was already in use a bit further down.
Comment #12
jhodgdonThe docs look good to me now, except one small typo:
an URL -> a URL
I am still suspicious of the code changes, however, and you'll need to find someone else to review those.
Comment #13
andileco commentedPatch with the typo corrected.
Comment #14
mikeker commentedComment #15
mondrakeRerolled 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.
Comment #16
mondrakeUpdated IS and Beta Evaluation to remove references to code changes that no longer apply.
Comment #17
googletorp commented@jhodgdon This is now a pure documentation cleanup. You reviewed this earlier so is it fine to RTBC?
Comment #20
jhodgdonIt's mostly good... maybe I wasn't too careful in my last review. But this block has some problems:
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.
Comment #21
mikeker commentedThis 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.
Comment #22
jhodgdonRegarding #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.
Comment #23
mondrakeTried to address feedback from #20 to #22.
@mikeker - I hope I did not step on your toes :)
Comment #24
jhodgdonYeah! This is very very close. I think we can make it even better with a few small changes though:
So, we actually have a slightly different standard syntax for indicating an optional parameter. It would say:
Let's do that here. Sorry for not bringing that up earlier.
We should do the same as above here with (optional)
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.
Can we say "URL query parameters" instead of just "query parameters" here too?
Get => Gets
Thanks!
Comment #25
snehi commentedDone.
Comment #26
jhodgdonThere 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!
Comment #27
snehi commentedDone.
Comment #28
jhodgdonGreat, thanks!
Comment #30
xjmGreat 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-wordsto 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!