HHH-16648 Documentation for implementing custom JPQL/HQL functions

[FelixDes]

I propose a technology for creating custom JPQL/HQL functions (code and documentation).

https://hibernate.atlassian.net/browse/HHH-16648

[hibernate-github-bot]

Thanks for your pull request!

This pull request does not follow the contribution rules. Could you have a look?

❌ All commit messages should start with a JIRA issue key matching pattern HHH-\d+
    ↳ Offending commits: [adc1885]
❌ The pull request description must contain the license agreement text.
    ↳ The description of this pull request must contain the following license agreement text:

----------------------
By submitting this pull request, I confirm that my contribution is made under the terms of the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0.txt)
and can be relicensed under the terms of the [LGPL v2.1 license](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt) in the future at the maintainers' discretion.
For more information on licensing, please check [here](https://github.com/hibernate/hibernate-orm/blob/main/CONTRIBUTING.md#legal).

----------------------

› This message was automatically generated.

[FelixDes]

I would appreciate feedback on the status of this pull request. Is the code being reviewed or rejected?

[beikov]

I'm sorry this takes so long. Your PR is very much appreciated and we will look into it. We are currently busy with other things. I added your PR to my todo list, so be assured that I will review it eventually.

[FelixDes]

Thank you very much!

[FelixDes]

Please let me know what needs to be fixed or added in my code for you to accept my pull request.

[gavinking]

I'm really not sure how much of an open invitation we really want to be giving to users to start depending on some of these SPIs in their application programs.

Yes, it's true that org.hibernate.sql.ast and org.hibernate.sql.ast.tree are technically SPIs, but they're both marked @Incubating for the very good reason that:

1. they're an extremely broad SPI surface, and
2. not really stabilized in any meaningful sense.

So I would leave this undocumented for now.