Enhance documentation at Restrict

[otaviojava]

I started creating documentation at the Restrict interface when I made a branch to begin implementing it.

The straightforward, precise methods I've created documentation are still a lot of work to go, but it will make sense to break on more PRs since it is considerable work.

[njr-11]

We decided not to add Javadoc and spec doc on Restrictions until we are more certain that the API is where we want it and unlikely to further change. Maybe we are nearly ready to make that decision, but there is currently #915 open for additional changes to the API, which will already make the API out of sync with what you wrote into the very first method of this PR.

Doing a good job on the Javadoc is important because it is how users will come to understand (or not understand) our API and how to use it. This will mean a big investment on our part and should not be done all at once. When it is time, I would expect multiple PRs with work done in smaller chunks, covering only a few classes at a time that we can write and review in depth to ensure we get it all right.

Only looking at the first method here, there is at least one incorrect statement, and it collides with the outstanding PR making further API changes, and it seems oriented toward a Jakarta Data provider rather than a Jakarta Data user. We are not yet ready to invest in the Javadoc. Hopefully soon, but we are not there yet.

[otaviojava]

I will close this one and open it as a small documentation step.