RFR: 8267858: Document that title property in WebEngine gets updated asynchronously

[Arun Joseph]

On Thu, 3 Jun 2021 23:53:48 GMT, Kevin Rushforth <kcr at openjdk.org> wrote:

>> modules/javafx.web/src/main/java/javafx/scene/web/WebEngine.java line 441:
>> 
>>> 439: 
>>> 440:     /*
>>> 441:      * The page title. This gets updated asynchronously.
>> 
>> Is there any more information or guarantee when the update is expected to be complete, or is it truly asynchronous? I we know that this will happen between the current pulse and the next one, that might be helpful to developers (although I agree waiting for the titleProperty to be changed is the better approach).
>> If there is no link beween the webkit thread that gets the title and the quantum renderer, it is really asynchronous and in that case tricks like waiting for a few pulses won't help either -- but it would be good to mention that so that developers don't create workarounds that might work in some cases and fail in others.
>
> I had exactly the same thought about the need to document it more clearly. Maybe something like:
> 
> "This property will be updated asynchronously some time after the page is loaded. Applications should not rely on any particular timing, but should listen for changes to this property, or bind to it, to know when it has been updated."
> 
> Btw, you modified an ordinary comment, not a javadoc comment. The newly added sentence needs to go on the javadoc comment, which is on the `titleProperty` method a few lines down from here. Be sure to run `gradle javadoc` and look at the generated docs.

I've modified the right javadoc comment now.

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

PR: https://git.openjdk.java.net/jfx/pull/522