Documentation enhancement: Add more usable examples in Limiting Query Results

[Hdvlp]

The documentation of Limiting Query Results can be enhanced by adding more usable examples.

I have added a repository to show that some example code builds and some fails. It is a time-saver to see more usable examples and use these examples before running into problems I encountered earlier in the error messages.

To handle At least 1 parameter(s) provided but only 0 parameter(s) present in query properly, a developer needs to know if the parameter inside the method name or if the parameter inside the brackets should be added. This is a potentially confusing area just by looking at this line of error message.

    User findByUsername(String username); // builds
    User findByLastname(String lastname); // builds
    User findFirstOrderByUsername(String username); // builds
    User findFirstOrderByLastname(String username); // builds

    User findFirstByOrderByUsernameAsc(); // builds
    User findFirstByOrderByLastnameAsc(); // builds
    User findFirstByOrderByFirstnameAsc(); // builds

    User findFirstByLastnameOrderByUsernameAsc(String lastname); // builds
    User findFirstByLastnameOrderByLastnameAsc(String lastname); // builds
    User findFirstByLastnameOrderByFirstnameAsc(String lastname); // builds
    User findFirstByLastnameOrderByIdAsc(String lastname); // builds

    User findFirstByUsernameOrderByUsernameAsc(String username); // builds
    User findFirstByUsernameOrderByUsername(String username); // builds
    User findFirstByUsernameOrderByUsernameDesc(String username); // builds

    User findFirstByOrderByUsername(String username); // fails to build

    User findFirstByOrderByUsernameAsc(String username); // fails to build

[mp911de]

I fail to understand what the documentation about limiting has to do with the At least 1 parameter(s) provided but only 0 parameter(s) present in query validation.

Also, we have 7 examples that illustrate the practical application of part tree limiting, Limit and Pageable usage. Not sure there's much of an gap.

[Hdvlp]

An objective is to allow some ready-to-use examples to appear in the documentation. This is just to make life easier. By providing more examples, the error of only 0 parameter(s) present in query could be more obvious to the reader of the documentation. The error alone is not a reason for adding more examples. Trying to make life easier, and trying to make things more obvious could be reasons for adding examples.

I do not know if such ready-to-use examples fit the style of the documentation. If they do not fit the style of the current documentation, maybe they can be included in some other kind of supplementary notes, etc.

[schauder]

I'll try to comment on all the aspects I see in this ticket:

1. I think our examples are quite ready to use already. If at all I see small issue about the examples we have: Some of them have an additional filter parameter, while some don't, but all that have use some kind of special parameter (Pageable, Sort) as well, which might leave the impression there is a relation between the two, where there isn't. But this is not what you are talking about, are you?
   If you want to improve the documentation by moving the filtering property from one of the methods with special parameters to one without, I would happily accept it, but I wouldn't leave this ticket open for that.

2. The (working) examples in your repository are quite repetitive. For example:

   User findFirstByOrderByUsernameAsc();
   User findFirstByOrderByLastnameAsc();
   User findFirstByOrderByFirstnameAsc();

   All demonstrate the exact same pattern and only differ by the property that is used for ordering. I don't think we want this kind of redundancy in our documentation, or any kind of material maintained by us.

   Also, many of these examples are not related to limiting queries at all, so they would belong into https://docs.spring.io/spring-data/jpa/reference/repositories/query-methods-details.html#repositories.query-methods.query-creation if at all. But again, there are plenty of examples already.
   Any additional example would need to demonstrate more than just another combination of features.

3. The issue of the error message.
   We rarely explicitly documented error scenarios.
   Searching for the error message brings up plenty of Stackoverflow questions and answers. It turns out there are tons of reasons, to end up with an error message At least 1 parameter(s) provided but only 0 parameter(s) present in query or similar:

   • a straight forward mismatch between properties referenced in the method name and those provided as arguments, as demonstrated in your example. This doesn't seem to be very common on SO. I'd assume because people don't make that mistake in the first place or quickly figure out what is wrong.

   • combining features that don't work together, like query derivation an specifications.

   • Using wrong types, like PageRequest instead of Pageable

   • And probably many more.

   I think it is futile to try to document these in the reference documentation and we would quickly end up with a document that talks more about stuff that doesn't work than what does work. Stackoverflow seems to be a great place for this kind of documentation.

In Summary: I don't see a potential improvement in the documentation here, with the tiny exception mentioned under 1.

I'll therefore close this ticket.