[java] Actions javadoc: #perform vs #build

[alb-i986]

Description

Slightly improving the documentation.
Pointing out that it’s #perform what the user needs to call at the end of the method chain to actually perform the actions.

Motivation and Context

It would be natural for one who is familiar with the Builder pattern, and it's the first time that he/she uses the Actions class (exploring the API with method completion), to come up with something like this:

new Actions(driver)
  .this()
  .that()
  [..]
  .build();

And expect that it will work.

Then, when they run their test and find that something didn't work, it's not going to be easy to figure out what went wrong. More specifically, to trace it back to the call to build().

This PR is trying to solve that by adding a warning in the javadoc.

Although I would prefer the build() method to behave as perform() (and deprecate perform() afterwards).

This comes from a personal experience, where I tried to use the Actions class after some time (a few years) I hadn't used it and I forgot that you need to call perform() and not build().

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Javadoc improvement

Checklist

• I have read the contributing document.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.

[shs96c]

Fair point, well made. :)

[shs96c]

Thank you for clarifying things. It's appreciated!