From 8a6c5eb2c0ea5b7fcdfebb9281de7cf6261b1a3e Mon Sep 17 00:00:00 2001 From: Dan Royer Date: Sun, 7 Jan 2024 14:14:38 -0800 Subject: [PATCH] Cleaning up javadoc warnings. --- pom.xml | 1 + .../application/ConversationEvent.java | 4 +- .../convenience/AnsiColors.java | 285 ++++++++++++++---- .../com/marginallyclever/convenience/Ray.java | 3 +- .../com/marginallyclever/ro3/apps/App.java | 8 + .../ro3/apps/actions/AddNode.java | 5 +- .../ro3/apps/nodeselector/NodeSelector.java | 1 + .../com/marginallyclever/ro3/mesh/Mesh.java | 2 +- .../ro3/raypicking/RayHit.java | 3 + .../ro3/view/ViewProvider.java | 1 + .../ro3/view/package-info.java | 26 +- .../marginallyclever/util/Ancestryable.java | 3 +- .../util/MarginallyCleverPreferences.java | 4 +- ...arginallyCleverPreferencesFileFactory.java | 3 +- .../MarginallyCleverPreferencesHelper.java | 1 + .../util/PropertiesFileHelper.java | 1 + 16 files changed, 270 insertions(+), 81 deletions(-) diff --git a/pom.xml b/pom.xml index 16fbeaec4..4f07c628a 100644 --- a/pom.xml +++ b/pom.xml @@ -158,6 +158,7 @@ maven-javadoc-plugin 3.6.3 + none ${minimum.java.version} docs com.marginallyclever.robotoverlord.* diff --git a/src/main/java/com/marginallyclever/communications/application/ConversationEvent.java b/src/main/java/com/marginallyclever/communications/application/ConversationEvent.java index e08ef6283..59156c9bc 100644 --- a/src/main/java/com/marginallyclever/communications/application/ConversationEvent.java +++ b/src/main/java/com/marginallyclever/communications/application/ConversationEvent.java @@ -1,7 +1,9 @@ package com.marginallyclever.communications.application; /** - * + * {@link ConversationEvent} is a simple record to hold a conversation event. + * @param whoSpoke the name of the person who spoke + * @param whatWasSaid what was said */ public record ConversationEvent(String whoSpoke, String whatWasSaid) { @Override diff --git a/src/main/java/com/marginallyclever/convenience/AnsiColors.java b/src/main/java/com/marginallyclever/convenience/AnsiColors.java index 62bf2b019..2190dfad4 100644 --- a/src/main/java/com/marginallyclever/convenience/AnsiColors.java +++ b/src/main/java/com/marginallyclever/convenience/AnsiColors.java @@ -7,75 +7,246 @@ */ public class AnsiColors { // Reset - public static final String RESET = "\033[0m"; // Text Reset + /** + * Text Reset + */ + public static final String RESET = "\033[0m"; // Regular Colors - public static final String BLACK = "\033[0;30m"; // BLACK - public static final String RED = "\033[0;31m"; // RED - public static final String GREEN = "\033[0;32m"; // GREEN - public static final String YELLOW = "\033[0;33m"; // YELLOW - public static final String BLUE = "\033[0;34m"; // BLUE - public static final String PURPLE = "\033[0;35m"; // PURPLE - public static final String CYAN = "\033[0;36m"; // CYAN - public static final String WHITE = "\033[0;37m"; // WHITE + /** + * BLACK + */ + public static final String BLACK = "\033[0;30m"; + /** + * RED + */ + public static final String RED = "\033[0;31m"; + /** + * GREEN + */ + public static final String GREEN = "\033[0;32m"; + /** + * YELLOW + */ + public static final String YELLOW = "\033[0;33m"; + /** + * BLUE + */ + public static final String BLUE = "\033[0;34m"; + /** + * PURPLE + */ + public static final String PURPLE = "\033[0;35m"; + /** + * CYAN + */ + public static final String CYAN = "\033[0;36m"; + /** + * WHITE + */ + public static final String WHITE = "\033[0;37m"; // Bold - public static final String BLACK_BOLD = "\033[1;30m"; // BLACK - public static final String RED_BOLD = "\033[1;31m"; // RED - public static final String GREEN_BOLD = "\033[1;32m"; // GREEN - public static final String YELLOW_BOLD = "\033[1;33m"; // YELLOW - public static final String BLUE_BOLD = "\033[1;34m"; // BLUE - public static final String PURPLE_BOLD = "\033[1;35m"; // PURPLE - public static final String CYAN_BOLD = "\033[1;36m"; // CYAN - public static final String WHITE_BOLD = "\033[1;37m"; // WHITE + /** + * BLACK + */ + public static final String BLACK_BOLD = "\033[1;30m"; + /** + * RED + */ + public static final String RED_BOLD = "\033[1;31m"; + /** + * GREEN + */ + public static final String GREEN_BOLD = "\033[1;32m"; + /** + * YELLOW + */ + public static final String YELLOW_BOLD = "\033[1;33m"; + /** + * BLUE + */ + public static final String BLUE_BOLD = "\033[1;34m"; + /** + * PURPLE + */ + public static final String PURPLE_BOLD = "\033[1;35m"; + /** + * CYAN + */ + public static final String CYAN_BOLD = "\033[1;36m"; + /** + * WHITE + */ + public static final String WHITE_BOLD = "\033[1;37m"; // Underline - public static final String BLACK_UNDERLINED = "\033[4;30m"; // BLACK - public static final String RED_UNDERLINED = "\033[4;31m"; // RED - public static final String GREEN_UNDERLINED = "\033[4;32m"; // GREEN - public static final String YELLOW_UNDERLINED = "\033[4;33m"; // YELLOW - public static final String BLUE_UNDERLINED = "\033[4;34m"; // BLUE - public static final String PURPLE_UNDERLINED = "\033[4;35m"; // PURPLE - public static final String CYAN_UNDERLINED = "\033[4;36m"; // CYAN - public static final String WHITE_UNDERLINED = "\033[4;37m"; // WHITE + /** + * BLACK + */ + public static final String BLACK_UNDERLINED = "\033[4;30m"; + /** + * RED + */ + public static final String RED_UNDERLINED = "\033[4;31m"; + /** + * GREEN + */ + public static final String GREEN_UNDERLINED = "\033[4;32m"; + /** + * YELLOW + */ + public static final String YELLOW_UNDERLINED = "\033[4;33m"; + /** + * BLUE + */ + public static final String BLUE_UNDERLINED = "\033[4;34m"; + /** + * PURPLE + */ + public static final String PURPLE_UNDERLINED = "\033[4;35m"; + /** + * CYAN + */ + public static final String CYAN_UNDERLINED = "\033[4;36m"; + /** + * WHITE + */ + public static final String WHITE_UNDERLINED = "\033[4;37m"; // Background - public static final String BLACK_BACKGROUND = "\033[40m"; // BLACK - public static final String RED_BACKGROUND = "\033[41m"; // RED - public static final String GREEN_BACKGROUND = "\033[42m"; // GREEN - public static final String YELLOW_BACKGROUND = "\033[43m"; // YELLOW - public static final String BLUE_BACKGROUND = "\033[44m"; // BLUE - public static final String PURPLE_BACKGROUND = "\033[45m"; // PURPLE - public static final String CYAN_BACKGROUND = "\033[46m"; // CYAN - public static final String WHITE_BACKGROUND = "\033[47m"; // WHITE + /** + * BLACK + */ + public static final String BLACK_BACKGROUND = "\033[40m"; + /** + * RED + */ + public static final String RED_BACKGROUND = "\033[41m"; + /** + * GREEN + */ + public static final String GREEN_BACKGROUND = "\033[42m"; + /** + * YELLOW + */ + public static final String YELLOW_BACKGROUND = "\033[43m"; + /** + * BLUE + */ + public static final String BLUE_BACKGROUND = "\033[44m"; + /** + * PURPLE + */ + public static final String PURPLE_BACKGROUND = "\033[45m"; + /** + * CYAN + */ + public static final String CYAN_BACKGROUND = "\033[46m"; + /** + * WHITE + */ + public static final String WHITE_BACKGROUND = "\033[47m"; // High Intensity - public static final String BLACK_BRIGHT = "\033[0;90m"; // BLACK - public static final String RED_BRIGHT = "\033[0;91m"; // RED - public static final String GREEN_BRIGHT = "\033[0;92m"; // GREEN - public static final String YELLOW_BRIGHT = "\033[0;93m"; // YELLOW - public static final String BLUE_BRIGHT = "\033[0;94m"; // BLUE - public static final String PURPLE_BRIGHT = "\033[0;95m"; // PURPLE - public static final String CYAN_BRIGHT = "\033[0;96m"; // CYAN - public static final String WHITE_BRIGHT = "\033[0;97m"; // WHITE + /** + * BLACK + */ + public static final String BLACK_BRIGHT = "\033[0;90m"; + /** + * RED + */ + public static final String RED_BRIGHT = "\033[0;91m"; + /** + * GREEN + */ + public static final String GREEN_BRIGHT = "\033[0;92m"; + /** + * YELLOW + */ + public static final String YELLOW_BRIGHT = "\033[0;93m"; + /** + * BLUE + */ + public static final String BLUE_BRIGHT = "\033[0;94m"; + /** + * PURPLE + */ + public static final String PURPLE_BRIGHT = "\033[0;95m"; + /** + * CYAN + */ + public static final String CYAN_BRIGHT = "\033[0;96m"; + /** + * WHITE + */ + public static final String WHITE_BRIGHT = "\033[0;97m"; // Bold High Intensity - public static final String BLACK_BOLD_BRIGHT = "\033[1;90m"; // BLACK - public static final String RED_BOLD_BRIGHT = "\033[1;91m"; // RED - public static final String GREEN_BOLD_BRIGHT = "\033[1;92m"; // GREEN - public static final String YELLOW_BOLD_BRIGHT = "\033[1;93m";// YELLOW - public static final String BLUE_BOLD_BRIGHT = "\033[1;94m"; // BLUE - public static final String PURPLE_BOLD_BRIGHT = "\033[1;95m";// PURPLE - public static final String CYAN_BOLD_BRIGHT = "\033[1;96m"; // CYAN - public static final String WHITE_BOLD_BRIGHT = "\033[1;97m"; // WHITE + /** + * BLACK + */ + public static final String BLACK_BOLD_BRIGHT = "\033[1;90m"; + /** + * RED + */ + public static final String RED_BOLD_BRIGHT = "\033[1;91m"; + /** + * GREEN + */ + public static final String GREEN_BOLD_BRIGHT = "\033[1;92m"; + /** + * YELLOW + */ + public static final String YELLOW_BOLD_BRIGHT = "\033[1;93m"; + /** + * BLUE + */ + public static final String BLUE_BOLD_BRIGHT = "\033[1;94m"; + /** + * PURPLE + */ + public static final String PURPLE_BOLD_BRIGHT = "\033[1;95m"; + /** + * CYAN + */ + public static final String CYAN_BOLD_BRIGHT = "\033[1;96m"; + /** + * WHITE + */ + public static final String WHITE_BOLD_BRIGHT = "\033[1;97m"; // High Intensity backgrounds - public static final String BLACK_BACKGROUND_BRIGHT = "\033[0;100m";// BLACK - public static final String RED_BACKGROUND_BRIGHT = "\033[0;101m";// RED - public static final String GREEN_BACKGROUND_BRIGHT = "\033[0;102m";// GREEN - public static final String YELLOW_BACKGROUND_BRIGHT = "\033[0;103m";// YELLOW - public static final String BLUE_BACKGROUND_BRIGHT = "\033[0;104m";// BLUE - public static final String PURPLE_BACKGROUND_BRIGHT = "\033[0;105m"; // PURPLE - public static final String CYAN_BACKGROUND_BRIGHT = "\033[0;106m"; // CYAN - public static final String WHITE_BACKGROUND_BRIGHT = "\033[0;107m"; // WHITE + /** + * BLACK + */ + public static final String BLACK_BACKGROUND_BRIGHT = "\033[0;100m"; + /** + * RED + */ + public static final String RED_BACKGROUND_BRIGHT = "\033[0;101m"; + /** + * GREEN + */ + public static final String GREEN_BACKGROUND_BRIGHT = "\033[0;102m"; + /** + * YELLOW + */ + public static final String YELLOW_BACKGROUND_BRIGHT = "\033[0;103m"; + /** + * BLUE + */ + public static final String BLUE_BACKGROUND_BRIGHT = "\033[0;104m"; + /** + * PURPLE + */ + public static final String PURPLE_BACKGROUND_BRIGHT = "\033[0;105m"; + /** + * CYAN + */ + public static final String CYAN_BACKGROUND_BRIGHT = "\033[0;106m"; + /** + * WHITE + */ + public static final String WHITE_BACKGROUND_BRIGHT = "\033[0;107m"; } diff --git a/src/main/java/com/marginallyclever/convenience/Ray.java b/src/main/java/com/marginallyclever/convenience/Ray.java index c447d7da0..50e4afd9d 100644 --- a/src/main/java/com/marginallyclever/convenience/Ray.java +++ b/src/main/java/com/marginallyclever/convenience/Ray.java @@ -5,10 +5,9 @@ import javax.vecmath.Vector3d; /** - * + * {@link Ray} is a starting point and a direction. * @author Dan Royer * @since 1.6.0 - * */ public class Ray { private final Point3d origin = new Point3d(); diff --git a/src/main/java/com/marginallyclever/ro3/apps/App.java b/src/main/java/com/marginallyclever/ro3/apps/App.java index 432412395..7181529e6 100644 --- a/src/main/java/com/marginallyclever/ro3/apps/App.java +++ b/src/main/java/com/marginallyclever/ro3/apps/App.java @@ -7,10 +7,18 @@ * All apps extend from App for Reflection. */ public class App extends JPanel { + /** + * Default constructor + */ public App() { super(); } + /** + * Constructor with layout manager + * + * @param layout the layout manager to use + */ public App(LayoutManager layout) { super(layout); } diff --git a/src/main/java/com/marginallyclever/ro3/apps/actions/AddNode.java b/src/main/java/com/marginallyclever/ro3/apps/actions/AddNode.java index db14342be..27d66485c 100644 --- a/src/main/java/com/marginallyclever/ro3/apps/actions/AddNode.java +++ b/src/main/java/com/marginallyclever/ro3/apps/actions/AddNode.java @@ -12,7 +12,10 @@ import java.util.function.Supplier; /** - * Add a new instance of a Node to every selected branches of the tree + * {@link AddNode} is an {@link AbstractAction} to add a new instance of a {@link Node} to every selected branch of the + * tree. It will ask the user which type of {@link Node} to add, then create an + * {@link com.marginallyclever.ro3.apps.commands.AddNode} command to add the new {@link Node}. + * @param the type of {@link Node} to add */ public class AddNode extends AbstractAction { private static final FactoryPanel nfd = new FactoryPanel<>(Registry.nodeFactory); diff --git a/src/main/java/com/marginallyclever/ro3/apps/nodeselector/NodeSelector.java b/src/main/java/com/marginallyclever/ro3/apps/nodeselector/NodeSelector.java index 4f007de9b..0066cc47f 100644 --- a/src/main/java/com/marginallyclever/ro3/apps/nodeselector/NodeSelector.java +++ b/src/main/java/com/marginallyclever/ro3/apps/nodeselector/NodeSelector.java @@ -22,6 +22,7 @@ * type T.

*

{@link NodeSelector} also provides a find button. The find action changes the global selection, which * updates any other systems listening to the selection.

+ * @param the type of {@link Node} to select */ public class NodeSelector extends JPanel { private T subject; diff --git a/src/main/java/com/marginallyclever/ro3/mesh/Mesh.java b/src/main/java/com/marginallyclever/ro3/mesh/Mesh.java index 788cb09df..646497359 100644 --- a/src/main/java/com/marginallyclever/ro3/mesh/Mesh.java +++ b/src/main/java/com/marginallyclever/ro3/mesh/Mesh.java @@ -19,7 +19,7 @@ /** *

{@link Mesh} contains the vertex data for a 3D model. It may also contain normal, color, and texture data.

- *

It uses Vertex Array Objects and Vertex + *

It uses Vertex Array Objects and Vertex * Buffer Objects to optimize rendering large collections of triangles.

* @author Dan Royer */ diff --git a/src/main/java/com/marginallyclever/ro3/raypicking/RayHit.java b/src/main/java/com/marginallyclever/ro3/raypicking/RayHit.java index f66b61cda..6524a8fe9 100644 --- a/src/main/java/com/marginallyclever/ro3/raypicking/RayHit.java +++ b/src/main/java/com/marginallyclever/ro3/raypicking/RayHit.java @@ -6,6 +6,9 @@ /** * A ray hit is a record of a ray hitting a {@link MeshInstance} at a certain distance. + * @param target the MeshInstance that the {@link com.marginallyclever.convenience.Ray} intersected. + * @param distance the distance from the {@link com.marginallyclever.convenience.Ray} origin to the point of contact. + * @param normal the normal of the {@link com.marginallyclever.ro3.mesh.Mesh} at the point of contact, in world space. * @author Dan Royer * @since 2.5.0 */ diff --git a/src/main/java/com/marginallyclever/ro3/view/ViewProvider.java b/src/main/java/com/marginallyclever/ro3/view/ViewProvider.java index 86f403eb5..8e5188568 100644 --- a/src/main/java/com/marginallyclever/ro3/view/ViewProvider.java +++ b/src/main/java/com/marginallyclever/ro3/view/ViewProvider.java @@ -5,6 +5,7 @@ /** * Classes implementing this interface are saying that they can provide a Swing component that can be used to view * or manipulate the given object. + * @param The type of object to be viewed or manipulated. */ public interface ViewProvider { /** diff --git a/src/main/java/com/marginallyclever/ro3/view/package-info.java b/src/main/java/com/marginallyclever/ro3/view/package-info.java index ce30b0e5a..709715541 100644 --- a/src/main/java/com/marginallyclever/ro3/view/package-info.java +++ b/src/main/java/com/marginallyclever/ro3/view/package-info.java @@ -1,14 +1,14 @@ +/* +

Suppose there are one or more classes that provide different views of a model, in the sense of a + model-view-controller design + pattern.

+

When class A provides a {@link com.marginallyclever.ro3.view.View} for model class B, A should be annotated + View(of=B.class). A must also implement the {@link com.marginallyclever.ro3.view.ViewProvider} + interface. {@link com.marginallyclever.ro3.view.ViewProvider} then empowers other systems to locate and + build the Swing GUI for A.

+

Annotating a {@link com.marginallyclever.ro3.view.View} and failing to implement the + {@link com.marginallyclever.ro3.view.ViewProvider} interface will cause a test to fail.

+ +

This system allows for modular and dynamic view creation for various data types in a Swing-based application.

+ */ package com.marginallyclever.ro3.view; -/** - *

Suppose there are one or more classes that provide different views of a model, in the sense of a - * model-view-controller design - * pattern.

- *

When class A provides a {@link com.marginallyclever.ro3.view.View} for model class B, A should be annotated - * View(of=B.class). A must also implement the {@link com.marginallyclever.ro3.view.ViewProvider} - * interface. {@link com.marginallyclever.ro3.view.ViewProvider} then empowers other systems to locate and - * build the Swing GUI for A.

- *

Annotating a {@link com.marginallyclever.ro3.view.View} and failing to implement the - * {@link com.marginallyclever.ro3.view.ViewProvider} interface will cause a test to fail.

- * - *

This system allows for modular and dynamic view creation for various data types in a Swing-based application.

- */ \ No newline at end of file diff --git a/src/main/java/com/marginallyclever/util/Ancestryable.java b/src/main/java/com/marginallyclever/util/Ancestryable.java index 17618ab43..be4870f96 100644 --- a/src/main/java/com/marginallyclever/util/Ancestryable.java +++ b/src/main/java/com/marginallyclever/util/Ancestryable.java @@ -4,11 +4,11 @@ import java.util.prefs.Preferences; /** + * TODO add description * @author Peter Colapietro * @since v7.1.4 */ public interface Ancestryable { - /** * @return ?? */ @@ -18,5 +18,4 @@ public interface Ancestryable { * @return ?? */ Map getRoot(); - } diff --git a/src/main/java/com/marginallyclever/util/MarginallyCleverPreferences.java b/src/main/java/com/marginallyclever/util/MarginallyCleverPreferences.java index d9f0fcae3..aa224b7b8 100644 --- a/src/main/java/com/marginallyclever/util/MarginallyCleverPreferences.java +++ b/src/main/java/com/marginallyclever/util/MarginallyCleverPreferences.java @@ -12,11 +12,9 @@ import java.util.prefs.Preferences; /** - * Created on 6/7/15. - * - * @author Peter Colapietro * See Java Preferences using a file as the backing store * See SO answer to: How to synchronize file access in a Java servlet? + * @author Peter Colapietro * @since v7.1.4 */ public class MarginallyCleverPreferences extends AbstractPreferences implements Ancestryable { diff --git a/src/main/java/com/marginallyclever/util/MarginallyCleverPreferencesFileFactory.java b/src/main/java/com/marginallyclever/util/MarginallyCleverPreferencesFileFactory.java index 099a9845f..dc93c79d6 100644 --- a/src/main/java/com/marginallyclever/util/MarginallyCleverPreferencesFileFactory.java +++ b/src/main/java/com/marginallyclever/util/MarginallyCleverPreferencesFileFactory.java @@ -11,8 +11,9 @@ import java.util.prefs.PreferencesFactory; /** - * @author Peter Colapietro * See Java Preferences using a file as the backing store + * @param AbstractPreferences + * @author Peter Colapietro * @since v7.1.4 */ public final class MarginallyCleverPreferencesFileFactory implements PreferencesFactory { diff --git a/src/main/java/com/marginallyclever/util/MarginallyCleverPreferencesHelper.java b/src/main/java/com/marginallyclever/util/MarginallyCleverPreferencesHelper.java index 69abf72d9..1ce4eed07 100644 --- a/src/main/java/com/marginallyclever/util/MarginallyCleverPreferencesHelper.java +++ b/src/main/java/com/marginallyclever/util/MarginallyCleverPreferencesHelper.java @@ -14,6 +14,7 @@ import java.util.prefs.Preferences; /** + * Helps with the command line interface for the MarginallyCleverPreferences class. * @author Peter Colapietro * @since v7.1.4 */ diff --git a/src/main/java/com/marginallyclever/util/PropertiesFileHelper.java b/src/main/java/com/marginallyclever/util/PropertiesFileHelper.java index 6f29c2724..dd45745a4 100644 --- a/src/main/java/com/marginallyclever/util/PropertiesFileHelper.java +++ b/src/main/java/com/marginallyclever/util/PropertiesFileHelper.java @@ -9,6 +9,7 @@ import java.util.Properties; /** + * Helps with accessing the robotoverlord.properties file. * @author Peter Colapietro * @since 2015-10-05 */