Update panache documentation: zero-based page index fix

[TyaraSchetgens]

To fetch page 7, Page with index 6 needs to be provided as index is zero-based

[github-actions]

🎊 PR Preview 26e4b8a has been successfully built and deployed to https://quarkus-pr-main-40703-preview.surge.sh/version/main/guides/

• Images of blog posts older than 3 months are not available.
• Newsletters older than 3 months are not available.

[gsmet]

LGTM from what I see of the code but I must admit, it's a bit weird to use 0-based pages.

As a user, you will always talk about page 1, not page 0.

[gsmet]

@FroMage I let you have a look at this one.

[TyaraSchetgens]

LGTM from what I see of the code but I must admit, it's a bit weird to use 0-based pages.

As a user, you will always talk about page 1, not page 0.

Agreed. In our code we are doing page - 1 everywhere. It is a bit messy.

Would it be feasable to make the page index start at 1 instead of 0?

[gsmet]

That would probably break all existing applications so that's probably something we won't be able to do unfortunately :/

[quarkus-bot]

Status for workflow Quarkus Documentation CI

This is the status report for running Quarkus Documentation CI on commit 7277d3a.

✅ The latest workflow run for the pull request has completed successfully.

It should be safe to merge provided you have a look at the other checks in the summary.

[FroMage]

I don't know about that. The javadocs of Page clearly mention it's zero-based. So "page 0" is the first page, and "page 7" is the eighth page. The comment you're refering to does not say "7th page" but "page 7", so it looks correct to me.

It's the same in most of the Java language. A List's first element will be at index 0.

Of course, both 0-based and 1-based indexing are valid, and depend on where they're being used. Spoken languages tend to use 1-based indexing, while math and C-inspired programming languages use 0-based indexing.

Using 0-based indexing in Java is the most intuitive and regular.

Perhaps this comment in the docs would have been clearer?

// get page 7 (pages are 0-based, so this is the 8th page in English)
List<Person> page7 = livingPersons.page(Page.of(7, 25)).list();

Would that help?

[gsmet]

I don't know about that. The javadocs of Page clearly mention it's zero-based. So "page 0" is the first page, and "page 7" is the eighth page. The comment you're refering to does not say "7th page" but "page 7", so it looks correct to me.

I think you're considering that from a programming POV whereas pages are more often than not used in the UI.

So the initial gripe was really about I have my pagination with page 1-7 (because that's what you have on the user side) and I have to translate it to 0-based pages before pushing it to Panache. It's not a big deal but pagination is a lot about UI and how you present the data.
Now I don't think either perpective is right or wrong, it's just not very intuitive when working on the UI side.

That being said, this ship has sailed so we just need to make sure the doc is clear.

[FroMage]

From a UI perspective you're right, but that's not the job of backends or APIs. The same is true when iterating indexes using Qute, everyone is used to adding +1 for humans.