From f8dae05a52dc28e3bbd5fe97da60a04cf87555d4 Mon Sep 17 00:00:00 2001 From: Lou H <41243237+louhy@users.noreply.github.com> Date: Sat, 8 Jun 2019 20:06:23 -0400 Subject: [PATCH] #1107-Fix Javadoc warnings in OpenJDK 9+ (#1112) --- .../java/com/jme3/bounding/BoundingBox.java | 6 ++--- .../com/jme3/bounding/BoundingSphere.java | 10 ++++----- .../jme3/cinematic/events/CameraEvent.java | 2 +- .../main/java/com/jme3/light/LightProbe.java | 2 +- .../java/com/jme3/material/RenderState.java | 22 +++++++++---------- .../java/com/jme3/material/Technique.java | 2 +- .../src/main/java/com/jme3/math/FastMath.java | 5 +++-- .../src/main/java/com/jme3/math/Ray.java | 5 +++-- .../src/main/java/com/jme3/renderer/Caps.java | 2 +- .../java/com/jme3/renderer/opengl/GL.java | 2 +- .../java/com/jme3/system/SystemListener.java | 2 +- .../main/java/com/jme3/texture/Texture.java | 8 ++++--- .../java/com/jme3/texture/TextureCubeMap.java | 16 +++++++------- .../src/main/java/com/jme3/util/ListSort.java | 5 +++-- .../src/main/java/com/jme3/util/SortUtil.java | 2 +- .../com/jme3/export/binary/ByteUtils.java | 2 +- .../material/plugins/ConditionParser.java | 12 +++++----- .../plugins/ShaderNodeLoaderDelegate.java | 4 ++-- .../jme3/network/serializing/Serializer.java | 2 +- 19 files changed, 57 insertions(+), 54 deletions(-) diff --git a/jme3-core/src/main/java/com/jme3/bounding/BoundingBox.java b/jme3-core/src/main/java/com/jme3/bounding/BoundingBox.java index c087950a3..6e422dea4 100644 --- a/jme3-core/src/main/java/com/jme3/bounding/BoundingBox.java +++ b/jme3-core/src/main/java/com/jme3/bounding/BoundingBox.java @@ -79,9 +79,9 @@ public class BoundingBox extends BoundingVolume { * Instantiate a BoundingBox with given center and extents. * * @param c the coordinates of the center of the box (not null, not altered) - * @param x the X-extent of the box (>=0, may be +Infinity) - * @param y the Y-extent of the box (>=0, may be +Infinity) - * @param z the Z-extent of the box (>=0, may be +Infinity) + * @param x the X-extent of the box (0 or greater, may be +Infinity) + * @param y the Y-extent of the box (0 or greater, may be +Infinity) + * @param z the Z-extent of the box (0 or greater, may be +Infinity) */ public BoundingBox(Vector3f c, float x, float y, float z) { this.center.set(c); diff --git a/jme3-core/src/main/java/com/jme3/bounding/BoundingSphere.java b/jme3-core/src/main/java/com/jme3/bounding/BoundingSphere.java index 3137f2cbf..7936c7224 100644 --- a/jme3-core/src/main/java/com/jme3/bounding/BoundingSphere.java +++ b/jme3-core/src/main/java/com/jme3/bounding/BoundingSphere.java @@ -173,11 +173,11 @@ public class BoundingSphere extends BoundingVolume { /** * Calculates a minimum bounding sphere for the set of points. The algorithm - * was originally found in C++ at - *

- * http://www.flipcode.com/cgi-bin/msg.cgi?showThread=COTD-SmallestEnclosingSpheres&forum=cotd&id=-1
broken link

- *

and translated to java by Cep21

- * + * was originally found in C++ at
+ * + * http://flipcode.com/archives/Smallest_Enclosing_Spheres.shtml
+ * and translated to java by Cep21 + * * @param points * The points to calculate the minimum bounds from. */ diff --git a/jme3-core/src/main/java/com/jme3/cinematic/events/CameraEvent.java b/jme3-core/src/main/java/com/jme3/cinematic/events/CameraEvent.java index 91b9ee5e1..8d2b70894 100644 --- a/jme3-core/src/main/java/com/jme3/cinematic/events/CameraEvent.java +++ b/jme3-core/src/main/java/com/jme3/cinematic/events/CameraEvent.java @@ -41,7 +41,7 @@ import java.io.IOException; /** * - * @author Rickard + * @author Rickard (neph1 @ github) */ public class CameraEvent extends AbstractCinematicEvent{ diff --git a/jme3-core/src/main/java/com/jme3/light/LightProbe.java b/jme3-core/src/main/java/com/jme3/light/LightProbe.java index c2e011c6c..a53c4ddbd 100644 --- a/jme3-core/src/main/java/com/jme3/light/LightProbe.java +++ b/jme3-core/src/main/java/com/jme3/light/LightProbe.java @@ -120,7 +120,7 @@ public class LightProbe extends Light implements Savable { // 1 | ay by cy | py | probe position // 2 | az bz cz | pz | ) // --|----------| - // 3 | sx sy sz sp | -> 1/probe radius + nbMipMaps + // 3 | sx sy sz sp | 1/probe radius + nbMipMaps // --scale-- *

* (ax, ay, az) is the pitch rotation axis diff --git a/jme3-core/src/main/java/com/jme3/material/RenderState.java b/jme3-core/src/main/java/com/jme3/material/RenderState.java index fea4d26e2..17bb78f68 100644 --- a/jme3-core/src/main/java/com/jme3/material/RenderState.java +++ b/jme3-core/src/main/java/com/jme3/material/RenderState.java @@ -272,27 +272,27 @@ public class RenderState implements Cloneable, Savable { /** * Additive blending. For use with glows and particle emitters. *

- * Result = Source Color + Destination Color -> (GL_ONE, GL_ONE) + * Result = Source Color + Destination Color -> (GL_ONE, GL_ONE) */ Additive, /** * Premultiplied alpha blending, for use with premult alpha textures. *

- * Result = Source Color + (Dest Color * (1 - Source Alpha) ) -> (GL_ONE, GL_ONE_MINUS_SRC_ALPHA) + * Result = Source Color + (Dest Color * (1 - Source Alpha) ) -> (GL_ONE, GL_ONE_MINUS_SRC_ALPHA) */ PremultAlpha, /** * Additive blending that is multiplied with source alpha. * For use with glows and particle emitters. *

- * Result = (Source Alpha * Source Color) + Dest Color -> (GL_SRC_ALPHA, GL_ONE) + * Result = (Source Alpha * Source Color) + Dest Color -> (GL_SRC_ALPHA, GL_ONE) */ AlphaAdditive, /** * Color blending, blends in color from dest color * using source color. *

- * Result = Source Color + (1 - Source Color) * Dest Color -> (GL_ONE, GL_ONE_MINUS_SRC_COLOR) + * Result = Source Color + (1 - Source Color) * Dest Color -> (GL_ONE, GL_ONE_MINUS_SRC_COLOR) */ Color, /** @@ -300,7 +300,7 @@ public class RenderState implements Cloneable, Savable { * using source alpha. *

* Result = Source Alpha * Source Color + - * (1 - Source Alpha) * Dest Color -> (GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA) + * (1 - Source Alpha) * Dest Color -> (GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA) */ Alpha, /** @@ -309,28 +309,28 @@ public class RenderState implements Cloneable, Savable { * The resulting alpha is the sum between the source alpha and the destination alpha. *

* Result.rgb = Source Alpha * Source Color + - * (1 - Source Alpha) * Dest Color -> (GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA) - * Result.a = 1 * Source Alpha + 1 * Dest Alpha -> (GL_ONE, GL_ONE) + * (1 - Source Alpha) * Dest Color -> (GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA) + * Result.a = 1 * Source Alpha + 1 * Dest Alpha -> (GL_ONE, GL_ONE) * */ AlphaSumA, /** * Multiplies the source and dest colors. *

- * Result = Source Color * Dest Color -> (GL_DST_COLOR, GL_ZERO) + * Result = Source Color * Dest Color -> (GL_DST_COLOR, GL_ZERO) */ Modulate, /** * Multiplies the source and dest colors then doubles the result. *

- * Result = 2 * Source Color * Dest Color -> (GL_DST_COLOR, GL_SRC_COLOR) + * Result = 2 * Source Color * Dest Color -> (GL_DST_COLOR, GL_SRC_COLOR) */ ModulateX2, /** * Opposite effect of Modulate/Multiply. Invert both colors, multiply and * then invert the result. *

- * Result = 1 - (1 - Source Color) * (1 - Dest Color) -> (GL_ONE, GL_ONE_MINUS_SRC_COLOR) + * Result = 1 - (1 - Source Color) * (1 - Dest Color) -> (GL_ONE, GL_ONE_MINUS_SRC_COLOR) */ Screen, /** @@ -338,7 +338,7 @@ public class RenderState implements Cloneable, Savable { * operation. This is directly equivalent to Photoshop's "Exclusion" blend. *

* Result = (Source Color * (1 - Dest Color)) + (Dest Color * (1 - Source Color)) - * -> (GL_ONE_MINUS_DST_COLOR, GL_ONE_MINUS_SRC_COLOR) + * -> (GL_ONE_MINUS_DST_COLOR, GL_ONE_MINUS_SRC_COLOR) */ Exclusion, /** diff --git a/jme3-core/src/main/java/com/jme3/material/Technique.java b/jme3-core/src/main/java/com/jme3/material/Technique.java index 5b02d77e7..a2fb1a037 100644 --- a/jme3-core/src/main/java/com/jme3/material/Technique.java +++ b/jme3-core/src/main/java/com/jme3/material/Technique.java @@ -169,7 +169,7 @@ public final class Technique { /** * Get the {@link DefineList} for dynamic defines. * - * Dynamic defines are used to implement material parameter -> define + * Dynamic defines are used to implement material parameter -- define * bindings as well as {@link TechniqueDefLogic} specific functionality. * * @return all dynamic defines. diff --git a/jme3-core/src/main/java/com/jme3/math/FastMath.java b/jme3-core/src/main/java/com/jme3/math/FastMath.java index e1683d214..49c993a09 100644 --- a/jme3-core/src/main/java/com/jme3/math/FastMath.java +++ b/jme3-core/src/main/java/com/jme3/math/FastMath.java @@ -91,7 +91,7 @@ final public class FastMath { * Get the next power of two of the given number. * * E.g. for an input 100, this returns 128. - * Returns 1 for all numbers <= 1. + * Returns 1 for all numbers less than or equal to 1. * * @param number The number to obtain the POT for. * @return The next power of two. @@ -942,7 +942,8 @@ final public class FastMath { * Converts a single precision (32 bit) floating point value * into half precision (16 bit). * - *

Source: + * ftp://www.fox-toolkit.org/pub/fasthalffloatconversion.pdf * * @param half The half floating point value as a short. * @return floating point value of the half. diff --git a/jme3-core/src/main/java/com/jme3/math/Ray.java b/jme3-core/src/main/java/com/jme3/math/Ray.java index 8b2ab216b..81e54d99f 100644 --- a/jme3-core/src/main/java/com/jme3/math/Ray.java +++ b/jme3-core/src/main/java/com/jme3/math/Ray.java @@ -43,8 +43,9 @@ import java.io.IOException; /** * Ray defines a line segment which has an origin and a direction. * That is, a point and an infinite ray is cast from this point. The ray is - * defined by the following equation: R(t) = origin + t*direction for t >= 0. - * + * defined by the following equation: {@literal + * R(t) = origin + t*direction for t >= 0. + * } * @author Mark Powell * @author Joshua Slack */ diff --git a/jme3-core/src/main/java/com/jme3/renderer/Caps.java b/jme3-core/src/main/java/com/jme3/renderer/Caps.java index b930863a6..d4094f015 100644 --- a/jme3-core/src/main/java/com/jme3/renderer/Caps.java +++ b/jme3-core/src/main/java/com/jme3/renderer/Caps.java @@ -238,7 +238,7 @@ public enum Caps { TextureBuffer, /** - * Supports floating point & half textures (Format.RGB16F) + * Supports floating point and half textures (Format.RGB16F) */ FloatTexture, diff --git a/jme3-core/src/main/java/com/jme3/renderer/opengl/GL.java b/jme3-core/src/main/java/com/jme3/renderer/opengl/GL.java index b2a57736f..bd3e2ea64 100644 --- a/jme3-core/src/main/java/com/jme3/renderer/opengl/GL.java +++ b/jme3-core/src/main/java/com/jme3/renderer/opengl/GL.java @@ -991,7 +991,7 @@ public interface GL { *

* Defines the scissor rectangle for all viewports. The scissor test is enabled or disabled for all viewports using {@link #glEnable Enable} or {@link #glDisable Disable} * with the symbolic constant {@link #GL_SCISSOR_TEST SCISSOR_TEST}. When disabled, it is as if the scissor test always passes. When enabled, if - * left <= xw < left + width and bottom <= yw < bottom + height for the scissor rectangle, then the scissor + * left <= xw < left + width and bottom <= yw < bottom + height for the scissor rectangle, then the scissor * test passes. Otherwise, the test fails and the fragment is discarded. * * @param x the left scissor rectangle coordinate. diff --git a/jme3-core/src/main/java/com/jme3/system/SystemListener.java b/jme3-core/src/main/java/com/jme3/system/SystemListener.java index e2e604a4b..132f47523 100644 --- a/jme3-core/src/main/java/com/jme3/system/SystemListener.java +++ b/jme3-core/src/main/java/com/jme3/system/SystemListener.java @@ -32,7 +32,7 @@ package com.jme3.system; /** - * The ContextListener> provides a means for an application + * The {@code SystemListener} provides a means for an application * to receive events relating to a context. */ public interface SystemListener { diff --git a/jme3-core/src/main/java/com/jme3/texture/Texture.java b/jme3-core/src/main/java/com/jme3/texture/Texture.java index 253423d00..e2166d42a 100644 --- a/jme3-core/src/main/java/com/jme3/texture/Texture.java +++ b/jme3-core/src/main/java/com/jme3/texture/Texture.java @@ -278,21 +278,23 @@ public abstract class Texture implements CloneableSmartAsset, Savable, Cloneable */ Off, - /** + /** + * {@code * Compares the 3rd texture coordinate R to the value * in this depth texture. If R <= texture value then result is 1.0, * otherwise, result is 0.0. If filtering is set to bilinear or trilinear * the implementation may sample the texture multiple times to provide - * smoother results in the range [0, 1]. + * smoother results in the range [0, 1].} */ LessOrEqual, /** + * {@code * Compares the 3rd texture coordinate R to the value * in this depth texture. If R >= texture value then result is 1.0, * otherwise, result is 0.0. If filtering is set to bilinear or trilinear * the implementation may sample the texture multiple times to provide - * smoother results in the range [0, 1]. + * smoother results in the range [0, 1].} */ GreaterOrEqual } diff --git a/jme3-core/src/main/java/com/jme3/texture/TextureCubeMap.java b/jme3-core/src/main/java/com/jme3/texture/TextureCubeMap.java index e2447fac2..f1a0f7d3b 100644 --- a/jme3-core/src/main/java/com/jme3/texture/TextureCubeMap.java +++ b/jme3-core/src/main/java/com/jme3/texture/TextureCubeMap.java @@ -44,14 +44,14 @@ import java.util.ArrayList; * Describes a cubemap texture. * The image specified by setImage must contain 6 data units, * each data contains a 2D image representing a cube's face. - * The slices are specified in this order:
- *
- * 0 => Positive X (+x)
- * 1 => Negative X (-x)
- * 2 => Positive Y (+y)
- * 3 => Negative Y (-y)
- * 4 => Positive Z (+z)
- * 5 => Negative Z (-z)
+ * The slices are specified in this order:
+ *
+ * 0 -- Positive X (+x)
+ * 1 -- Negative X (-x)
+ * 2 -- Positive Y (+y)
+ * 3 -- Negative Y (-y)
+ * 4 -- Positive Z (+z)
+ * 5 -- Negative Z (-z)
* * @author Joshua Slack */ diff --git a/jme3-core/src/main/java/com/jme3/util/ListSort.java b/jme3-core/src/main/java/com/jme3/util/ListSort.java index c45353a0c..517f2dd6b 100644 --- a/jme3-core/src/main/java/com/jme3/util/ListSort.java +++ b/jme3-core/src/main/java/com/jme3/util/ListSort.java @@ -52,12 +52,13 @@ import java.util.Comparator; * for optimal performance, but can be called several times if the length of the * list changes * + * {@code * Disclaimer : I was intrigued by the use of val >>> 1 in java 7 Timsort class * instead of val / 2 (integer division). Micro benching revealed that val >>> 1 * is twice faster than val / 2 in java 6 and has similar perf in java 7. The * following code uses val >>> 1 when ever a value needs to be divided by 2 and * rounded to its floor - * + * } * * @author Nehon */ @@ -66,7 +67,7 @@ public class ListSort { /** * Threshold for binary sort vs merge. Original algorithm use 64, java7 * TimSort uses 32 and I used 128, see this post for explanations : - * http://hub.jmonkeyengine.org/groups/development-discussion-jme3/forum/topic/i-got-that-sorted-out-huhuhu/ + * https://hub.jmonkeyengine.org/t/i-got-that-sorted-out-huhuhu/24478 */ private static final int MIN_SIZE = 128; private T[] array; diff --git a/jme3-core/src/main/java/com/jme3/util/SortUtil.java b/jme3-core/src/main/java/com/jme3/util/SortUtil.java index 51edc0adb..7628495f5 100644 --- a/jme3-core/src/main/java/com/jme3/util/SortUtil.java +++ b/jme3-core/src/main/java/com/jme3/util/SortUtil.java @@ -47,7 +47,7 @@ public class SortUtil { private static final int INSERTION_SORT_THRESHOLD = 7; - /** + /* procedure optimizedGnomeSort(a[]) pos := 1 last := 0 diff --git a/jme3-core/src/plugins/java/com/jme3/export/binary/ByteUtils.java b/jme3-core/src/plugins/java/com/jme3/export/binary/ByteUtils.java index f66a7fc7e..882cb529f 100644 --- a/jme3-core/src/plugins/java/com/jme3/export/binary/ByteUtils.java +++ b/jme3-core/src/plugins/java/com/jme3/export/binary/ByteUtils.java @@ -452,7 +452,7 @@ public class ByteUtils { * of bytes have been read. * * @param store - * the byte array to store in. Should have a length > bytes + * the byte array to store in. Array length must be greater than bytes param. * @param bytes * the number of bytes to read. * @param is diff --git a/jme3-core/src/plugins/java/com/jme3/material/plugins/ConditionParser.java b/jme3-core/src/plugins/java/com/jme3/material/plugins/ConditionParser.java index 07569ce90..2e1ff1aa2 100644 --- a/jme3-core/src/plugins/java/com/jme3/material/plugins/ConditionParser.java +++ b/jme3-core/src/plugins/java/com/jme3/material/plugins/ConditionParser.java @@ -79,13 +79,11 @@ public class ConditionParser { * additionally this methods updates the formattedExpression with uppercased * defines names * - * supported expression syntax example: - * - * "(LightMap && SeparateTexCoord) || !ColorMap" - * "#if (defined(LightMap) && defined(SeparateTexCoord)) || !defined(ColorMap)" - * "#ifdef LightMap" - * "#ifdef (LightMap && SeparateTexCoord) || !ColorMap" - * + * supported expression syntax example:

+ * {@code "(LightMap && SeparateTexCoord) || !ColorMap"}

+ * {@code "#if (defined(LightMap) && defined(SeparateTexCoord)) || !defined(ColorMap)"}

+ * {@code "#ifdef LightMap"}

+ * {@code "#ifdef (LightMap && SeparateTexCoord) || !ColorMap"}
* * @param expression the expression to parse * @return the list of defines diff --git a/jme3-core/src/plugins/java/com/jme3/material/plugins/ShaderNodeLoaderDelegate.java b/jme3-core/src/plugins/java/com/jme3/material/plugins/ShaderNodeLoaderDelegate.java index c8c674046..3e64d0d78 100644 --- a/jme3-core/src/plugins/java/com/jme3/material/plugins/ShaderNodeLoaderDelegate.java +++ b/jme3-core/src/plugins/java/com/jme3/material/plugins/ShaderNodeLoaderDelegate.java @@ -1058,11 +1058,11 @@ public class ShaderNodeLoaderDelegate { } /** - * merges 2 condition with the given operator + * Merges 2 conditions with the given operator * * @param condition1 the first condition * @param condition2 the second condition - * @param operator the operator ("&&" or "||&) + * @param operator the operator {@literal ("&&" or "||&)} * @return the merged condition */ public String mergeConditions(String condition1, String condition2, String operator) { diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/Serializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/Serializer.java index 26374762e..4e560fbfa 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/Serializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/Serializer.java @@ -153,7 +153,7 @@ public abstract class Serializer { /** * When set to true, classes that do not have intrinsic IDs in their - * @Serializable will not be auto-registered during write. Defaults + * {@code @Serializable } will not be auto-registered during write. Defaults * to true since this is almost never desired behavior with the way * this code works. Set to false to get the old permissive behavior. */