Warn about importance of ordering for all pagination classes

[Elkasitu]

The ordering recommendations given for the CursorPagination scheme
actually apply to all pagination schemes, an unsuspecting developer that
implements the more common LimitOffsetPagination or
PageNumberPagination classes is unlikely to be aware of the importance
of consistent ordering.

This commit moves the Details and limitations section out of the
CursorPagination section and puts it as the very first subsection of
the Pagination page so that it's one of the first things that
developers see.

Some examples of inconsistencies as well as how to deal with them are
given, and an extra way to change the ordering of a paginated view is
provided.

Fixes #6886

Hopefully this will prevent future developers from scratching their head and wondering why despite a view returning a count of X, going through all the pages yields Y records.

[tomchristie]

I'm not convinced that this section makes sense when moved around like this.

For example from a first look over - it discusses the ordering attribute on the pagination class. Which is specific to the CursorPagination class, rather than being generally applicable.

[Elkasitu]

You're right, when I wrote this patch I hadn't actually tried to implement CursorPagination yet so I assumed some of these things also applied to the other Pagination classes (like an interface).

I have made some changes, I kept it as a general section because the only Pagination class that is really different from the others is CursorPagination, so having a subsection per class seemed like a lot of duplicated text.

[Faki-140386]

Segue sempre sem fazer nenhuma alteração

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[Elkasitu]

@tomchristie any chance of ever getting something like this merged? I feel like it's an easy and dangerous trap to fall into

[auvipy]

@tomchristie any chance of ever getting something like this merged? I feel like it's an easy and dangerous trap to fall into

did you addressed the concerns @tomchristie initially raised?

[Elkasitu]

@auvipy Well there was only one concern which was about the ordering attribute of the CursorPagination class which I did address, you can see the changes I made in the second commit (can be squashed).

If there are any other concerns I'm willing to address them too

[auvipy]

I think it would be better to include for elaborate code example here including the pagination classes