[OO] Javadoc & readibility improvements

[subhramit]

Recently I learnt about @implSpec tags which are used to specify requirements/preconditions for methods.
This helped clean the documentation of my code a bit.

The tag shows up as "Implementation Requirements:" in javadoc as follows:

Additional:

• Fixed module export for gradle task javadoc
• Fixed some miscellaneous typos
• Changed some variable names for better readability

Mandatory checks

• I own the copyright of the code submitted and I licence it under the MIT license
• Change in CHANGELOG.md described in a way that is understandable for the average user (if change is visible to the user)
• Tests created for changes (if applicable)
• Manually tested changed features in running JabRef (always required)
• Screenshots added in PR description (for UI changes)
• Checked developer's documentation: Is the information available and up to date? If not, I outlined it in this pull request.
• Checked documentation: Is the information available and up to date? If not, I created an issue at https://github.com/JabRef/user-documentation/issues or, even better, I submitted a pull request to the documentation repository.

[subhramit]

Thought: Like we have priority classifications for issues, should we have labels for PRs as well such as "non-blocking", "non-breaking", "non-urgent", "low priority", etc.?

[calixtus]

Some reading about this tag: https://nipafx.dev/javadoc-tags-apiNote-implSpec-implNote/

[koppor]

Maybe convert to Markdown (/// instead of *) to have that rendered proply (Otherwise, you should use <ol> and <li>.

[subhramit]

Done

[subhramit]

@koppor I tried to generate the javadoc using the gradle task, but it failed due to the following two errors (something related to module export):

D:\git-repositories\JabRef\src\main\java\org\jabref\gui\search\GlobalSearchBar.java:68: error: package impl.org.controlsfx.skin is not visible
import impl.org.controlsfx.skin.AutoCompletePopup;
                          ^
  (package impl.org.controlsfx.skin is declared in module org.controlsfx.controls, which does not export it to module org.jabref)

D:\git-repositories\JabRef\src\main\java\org\jabref\gui\util\CustomRatingSkin.java:7: error: package impl.org.controlsfx.skin is not visible
import impl.org.controlsfx.skin.RatingSkin;
                          ^
  (package impl.org.controlsfx.skin is declared in module org.controlsfx.controls, which does not export it to module org.jabref)

cc: @calixtus

[calixtus]

You need to modify module-info.java, but don't ask me how, it's always try and error with me, I did not yet deep dive into java module system.

[Siedlerchr]

You need to add the add-export calls for the javadoc task

jabref/build.gradle

Lines 596 to 598 in 0dad3e1

	addMultilineStringsOption("-add-exports").setValue([
	'javafx.controls/com.sun.javafx.scene.control=org.jabref'
	])

This was from an old issue java9-modularity/gradle-modules-plugin#170

[subhramit]

@Siedlerchr ready for merge

obsolete