dlsc-software-consulting-gmbh · martinfrancois · Aug 25, 2019 · Aug 22, 2019 · Aug 25, 2019 · Aug 25, 2019
diff --git a/preferencesfx/pom.xml b/preferencesfx/pom.xml
@@ -98,6 +98,40 @@
                     <additionalJOption>-J-Djavafx.javadoc=true
                     </additionalJOption>
                     <docfilessubdirs>true</docfilessubdirs>
+                    <!-- force links to Java 8 documentation (should happen automatically
+                         but doesn't) -->
+                    <javaApiLinks>
+                        <property>
+                            <name>api_1.8</name>
+                            <value>https://docs.oracle.com/javase/8/docs/api/</value>
+                        </property>
+                    </javaApiLinks>
+                    <!-- Need to specify the following to support new tags
+                         'apiNote', 'implSpec', 'implNote' -->
+                    <tags>
+                        <tag>
+                            <name>apiNote</name>
+                            <placement>a</placement>
+                            <head>API Note:</head>
+                        </tag>
+                        <tag>
+                            <name>implSpec</name>
+                            <placement>a</placement>
+                            <head>Implementation Requirements:</head>
+                        </tag>
+                        <tag>
+                            <name>implNote</name>
+                            <placement>a</placement>
+                            <head>Implementation Note:</head>
+                        </tag>
+                        <tag><name>param</name></tag>
+                        <tag><name>return</name></tag>
+                        <tag><name>throws</name></tag>
+                        <tag><name>since</name></tag>
+                        <tag><name>version</name></tag>
+                        <tag><name>serialData</name></tag>
+                        <tag><name>see</name></tag>
+                    </tags>
                 </configuration>
                 <executions>
                     <execution>

diff --git a/preferencesfx/src/main/java/com/dlsc/preferencesfx/PreferencesFx.java b/preferencesfx/src/main/java/com/dlsc/preferencesfx/PreferencesFx.java
@@ -208,7 +208,7 @@ public void discardChanges() {
 
   /**
    * Defines whether the table to debug the undo / redo history should be shown in a dialog when
-   * pressing a key combination or not. <\br> Pressing Ctrl + Shift + H (Windows) or CMD + Shift + H
+   * pressing a key combination or not. <br> Pressing Ctrl + Shift + H (Windows) or CMD + Shift + H
    * (Mac) opens a dialog with the undo / redo history, shown in a table.
    *
    * @param debugState if true, pressing the key combination will open the dialog
@@ -253,6 +253,7 @@ public PreferencesFx i18n(TranslationService newValue) {
    *
    * @param eventType    the type of the events to receive by the handler
    * @param eventHandler the handler to register
+   * @return PreferencesFx to allow for chaining.
    * @throws NullPointerException if either event type or handler are {@code null}.
    */
   public PreferencesFx addEventHandler(EventType<PreferencesFxEvent> eventType,
@@ -268,6 +269,7 @@ public PreferencesFx addEventHandler(EventType<PreferencesFxEvent> eventType,
    *
    * @param eventType    the event type from which to unregister
    * @param eventHandler the handler to unregister
+   * @return PreferencesFx to allow for chaining.
    * @throws NullPointerException if either event type or handler are {@code null}.
    */
   public PreferencesFx removeEventHandler(EventType<PreferencesFxEvent> eventType,
@@ -289,6 +291,7 @@ public PreferencesFxView getView() {
    * Sets the dialog title.
    *
    * @param title the dialog title
+   * @return PreferencesFx to allow for chaining.
    */
   public PreferencesFx dialogTitle(String title) {
     preferencesFxDialog.setDialogTitle(title);
@@ -299,6 +302,7 @@ public PreferencesFx dialogTitle(String title) {
    * Sets the dialog icon.
    *
    * @param image the image to be used as the dialog icon.
+   * @return PreferencesFx to allow for chaining.
    */
   public PreferencesFx dialogIcon(Image image) {
     preferencesFxDialog.setDialogIcon(image);

diff --git a/preferencesfx/src/main/java/com/dlsc/preferencesfx/PreferencesFxEvent.java b/preferencesfx/src/main/java/com/dlsc/preferencesfx/PreferencesFxEvent.java
@@ -24,6 +24,8 @@ public class PreferencesFxEvent extends Event {
   /**
    * Creates a new instance of {@code PreferencesFxEvent} with event type set to {@code
    * EVENT_PREFERENCES_SAVED}.
+   *
+   * @return the newly created PreferencesFxEvent.
    */
   public static PreferencesFxEvent preferencesSavedEvent() {
     return new PreferencesFxEvent(EVENT_PREFERENCES_SAVED);
@@ -32,6 +34,8 @@ public static PreferencesFxEvent preferencesSavedEvent() {
   /**
    * Creates a new instance of {@code PreferencesFxEvent} with event type set to {@code
    * EVENT_PREFERENCES_NOT_SAVED}.
+   *
+   * @return the newly created PreferencesFxEvent.
    */
   public static PreferencesFxEvent preferencesNotSavedEvent() {
     return new PreferencesFxEvent(EVENT_PREFERENCES_NOT_SAVED);

diff --git a/preferencesfx/src/main/java/com/dlsc/preferencesfx/model/Category.java b/preferencesfx/src/main/java/com/dlsc/preferencesfx/model/Category.java
@@ -206,6 +206,7 @@ public void unmarkAll() {
    * service or its locale changes. Also applies the translation to all
    * contained sections.
    *
+   * @param translationService the translation service
    * @see com.dlsc.formsfx.model.structure.Group ::translate
    */
   public void translate(TranslationService translationService) {

diff --git a/preferencesfx/src/main/java/com/dlsc/preferencesfx/model/Group.java b/preferencesfx/src/main/java/com/dlsc/preferencesfx/model/Group.java
@@ -70,6 +70,8 @@ public Group description(String description) {
   /**
    * Returns the description of this group or if i18n is used, it will return the translated
    * description in the current locale.
+   *
+   * @return the description
    */
   public String getDescription() {
     if (preferencesGroup != null) {

diff --git a/preferencesfx/src/main/java/com/dlsc/preferencesfx/model/Setting.java b/preferencesfx/src/main/java/com/dlsc/preferencesfx/model/Setting.java
@@ -255,6 +255,8 @@ public static <P> Setting of(
   /**
    * Creates a setting of a custom defined field.
    *
+   * @param <F>         the field type
+   * @param <P>         the property type
    * @param description the title of this setting
    * @param field       custom Field object from FormsFX
    * @param property    to be bound, saved / loaded and used for undo / redo
@@ -434,6 +436,8 @@ public void unmark() {
   /**
    * Returns the description of this setting or if i18n is used, it will return the translated
    * description in the current locale.
+   *
+   * @return the description
    */
   public String getDescription() {
     if (field != null) {

diff --git a/preferencesfx/src/main/java/com/dlsc/preferencesfx/util/PreferencesFxUtils.java b/preferencesfx/src/main/java/com/dlsc/preferencesfx/util/PreferencesFxUtils.java
@@ -26,6 +26,9 @@ public class PreferencesFxUtils {
   /**
    * Returns a list of all the settings which are contained in a list of {@code categories}
    * recursively.
+   *
+   * @param categories the categories to fetch the settings from
+   * @return all settings of the categories
    */
   public static List<Setting> categoriesToSettings(List<Category> categories) {
     return categories.stream()
@@ -41,6 +44,9 @@ public static List<Setting> categoriesToSettings(List<Category> categories) {
   /**
    * Returns a list of all the settings which are contained in a list of {@code categories}
    * recursively.
+   *
+   * @param categories the categories to fetch the fields from
+   * @return all fields of the categories
    */
   public static List<Field> categoriesToFields(List<Category> categories) {
     return categories.stream()
@@ -130,6 +136,9 @@ public static List<Setting> filterSettingsByDescription(List<Setting> settings,
   /**
    * Returns a list of all the settings which are contained in a list of {@code groups}
    * recursively.
+   *
+   * @param groups the groups to fetch the settings from
+   * @return all settings of the groups
    */
   public static List<Setting> groupsToSettings(List<Group> groups) {
     return groups.stream()
@@ -155,6 +164,9 @@ public static List<Group> filterGroupsByDescription(List<Group> groups, String d
   /**
    * Returns a list of all the groups which are contained in a list of {@code categories}
    * recursively.
+   *
+   * @param categories the categories to fetch the groups from
+   * @return all groups of the categories
    */
   public static List<Group> categoriesToGroups(List<Category> categories) {
     return categories.stream()
@@ -166,6 +178,10 @@ public static List<Group> categoriesToGroups(List<Category> categories) {
 
   /**
    * Returns the amount of rows of a given {@code gridPane}, if present, -1 else.
+   *
+   * @param gridPane the grid pane to count the rows in
+   * @return the number of rows in the grid pane
+   *     or {@code -1} to indicate no children in the grid pane
    */
   public static int getRowCount(GridPane gridPane) {
     return gridPane.getChildren().stream().mapToInt(n -> {

diff --git a/preferencesfx/src/main/java/com/dlsc/preferencesfx/util/SearchHandler.java b/preferencesfx/src/main/java/com/dlsc/preferencesfx/util/SearchHandler.java
@@ -84,6 +84,7 @@ public class SearchHandler {
    * Initializes the SearchHandler by initially creating all necessary lists
    * for filtering and setting up the bindings.
    *
+   * @param model             the model of PreferencesFx
    * @param searchText        textProperty of a TextField where the search string is being input
    * @param predicateProperty of the rootItem of a {@link FilterableTreeItem}
    * @apiNote Must be called to make the filtering work.
@@ -109,6 +110,8 @@ private void initializeSearch() {
 
   /**
    * Initializes the search text by binding it and then adding a listener to react to changes.
+   *
+   * @param searchText the property of the search text UI element
    */
   public void initializeSearchText(StringProperty searchText) {
     bindSearchText(searchText);
@@ -216,7 +219,7 @@ private void markMatches() {
 
   /**
    * Compares three categories with decreasing priority from the first to the last category.
-   * {@see developer reference} for further information
+   * See developer reference for further information.
    *
    * @param setting       category to return, if settingsMatch is chosen
    * @param group         category to return, if groupMatch is chosen

diff --git a/preferencesfx/src/main/java/com/dlsc/preferencesfx/util/StorageHandlerImpl.java b/preferencesfx/src/main/java/com/dlsc/preferencesfx/util/StorageHandlerImpl.java
@@ -256,6 +256,7 @@ private String deprecatedHash(String key) {
    * to save / load as the key in {@link Preferences}, since those are guaranteed to be
    * maximum 64 chars long.
    *
+   * @param key the string to generate the hash from
    * @return SHA-256 representation of breadcrumb
    */
   public String hash(String key) {

diff --git a/preferencesfx/src/main/java/com/dlsc/preferencesfx/view/BreadCrumbView.java b/preferencesfx/src/main/java/com/dlsc/preferencesfx/view/BreadCrumbView.java
@@ -28,6 +28,7 @@ public class BreadCrumbView extends HBox implements View {
    * Constructs a new view, which displays the {@link BreadCrumbBar}.
    *
    * @param model the model of PreferencesFX
+   * @param undoRedoBox the box containing undo and redo buttons.
    */
   public BreadCrumbView(PreferencesFxModel model, UndoRedoBox undoRedoBox) {
     this.model = model;

diff --git a/preferencesfx/src/main/java/com/dlsc/preferencesfx/view/CategoryController.java b/preferencesfx/src/main/java/com/dlsc/preferencesfx/view/CategoryController.java
@@ -49,6 +49,10 @@ public CategoryPresenter getPresenter(Category category) {
 
   /**
    * Adds a view / presenter pair to the respective HashMaps.
+   *
+   * @param category of the categoryView
+   * @param view the view to add to the map
+   * @param presenter the presenter to add to the map
    */
   public void addView(Category category, CategoryView view, CategoryPresenter presenter) {
     views.put(category, view);

diff --git a/preferencesfx/src/main/java/com/dlsc/preferencesfx/view/NavigationPresenter.java b/preferencesfx/src/main/java/com/dlsc/preferencesfx/view/NavigationPresenter.java
@@ -126,6 +126,8 @@ private void addRecursive(FilterableTreeItem<Category> treeItem, List<Category>
 
   /**
    * Retrieves the currently selected category in the TreeSearchView.
+   *
+   * @return the currently selected category
    */
   public Category getSelectedCategory() {
     TreeItem<Category> selectedTreeItem =