more javadoc improvements

Author: stephengold

jme3-android/src/main/java/com/jme3/renderer/android/RendererUtil.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2019 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -71,6 +71,8 @@ public static void checkGLErrorForced() {
     /**
      * Checks for an EGL error and throws a {@link RendererException} if there
      * is one. Ignores the value of {@link RendererUtil#ENABLE_ERROR_CHECKING}.
+     * 
+     * @param egl (not null)
      */
     public static void checkEGLError(EGL10 egl) {
         int error = egl.eglGetError();

jme3-lwjgl/src/main/java/com/jme3/system/lwjgl/LwjglAbstractDisplay.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -68,7 +68,7 @@ public abstract class LwjglAbstractDisplay extends LwjglContext implements Runna
 
     /**
      * Set the title if it's a windowed display
-     * @param title
+     * @param title the desired title
      */
     @Override
     public abstract void setTitle(String title);
@@ -81,7 +81,8 @@ public abstract class LwjglAbstractDisplay extends LwjglContext implements Runna
 
     /**
      * Apply the settings, changing resolution, etc.
-     * @param settings
+     * @param settings the AppSettings to apply
+     * @throws LWJGLException for various error conditions
      */
     protected abstract void createContext(AppSettings settings) throws LWJGLException;
 
@@ -92,6 +93,8 @@ public abstract class LwjglAbstractDisplay extends LwjglContext implements Runna
 
     /**
      * Does LWJGL display initialization in the OpenGL thread
+     * 
+     * @return true if successful, otherwise false
      */
     protected boolean initInThread() {
         try {

jme3-lwjgl/src/main/java/com/jme3/system/lwjgl/LwjglCanvas.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -297,6 +297,9 @@ public void run(){
     /**
      * It seems it is best to use one pixel format for all shared contexts.
      * @see <a href="http://developer.apple.com/library/mac/#qa/qa1248/_index.html">http://developer.apple.com/library/mac/#qa/qa1248/_index.html</a>
+     * 
+     * @param forPbuffer true&rarr;zero samples, false&rarr;correct number of samples
+     * @return a new instance
      */
     protected PixelFormat acquirePixelFormat(boolean forPbuffer){
         if (forPbuffer){
@@ -333,6 +336,8 @@ protected PixelFormat acquirePixelFormat(boolean forPbuffer){
 
     /**
      * Makes sure the pbuffer is available and ready for use
+     * 
+     * @throws LWJGLException if the buffer can't be made current
      */
     protected void makePbufferAvailable() throws LWJGLException{
         if (pbuffer != null && pbuffer.isBufferLost()){

jme3-niftygui/src/main/java/com/jme3/niftygui/InputSystemJme.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -73,7 +73,7 @@ public void setResourceLoader(NiftyResourceLoader niftyResourceLoader) {
     /**
      * Must be set in order for nifty events to be forwarded correctly.
      *
-     * @param nifty
+     * @param nifty the Nifty instance to use
      */
     public void setNifty(Nifty nifty) {
         this.nifty = nifty;

jme3-niftygui/src/main/java/com/jme3/niftygui/JmeBatchRenderBackend.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -347,7 +347,8 @@ public void removeImageFromAtlas(final Image image, final int x, final int y, fi
      * {@link de.lessvoid.nifty.render.batch.spi.BatchRenderBackend}
      * implementation
      *
-     * @param shouldUseHighQualityTextures
+     * @param shouldUseHighQualityTextures true→higher quality,
+     * false→lower quality
      */
     @Override
     public void useHighQualityTextures(final boolean shouldUseHighQualityTextures) {
@@ -362,7 +363,8 @@ public void useHighQualityTextures(final boolean shouldUseHighQualityTextures) {
      * debugging when visually inspecting the atlas, since there will not be
      * portions of old images visible in currently unused atlas space.
      *
-     * @param shouldFill
+     * @param shouldFill true→overwrite with blank data, false→don't
+     * overwrite
      */
     @Override
     public void fillRemovedImagesInAtlas(final boolean shouldFill) {

jme3-niftygui/src/main/java/com/jme3/niftygui/RenderFontJme.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2012 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -44,7 +44,7 @@ public class RenderFontJme implements RenderFont {
     /**
      * Initialize the font.
      * @param name font filename
-     * @param display
+     * @param display (not null)
      */
     public RenderFontJme(String name, NiftyJmeDisplay display) {
         font = display.getAssetManager().loadFont(name);

jme3-niftygui/src/main/java/com/jme3/niftygui/SoundHandleJme.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2018 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -55,9 +55,10 @@ public SoundHandleJme(AudioRenderer ar, AudioNode node){
 
     /**
      * For streaming music only. (May need to loop..)
-     * @param ar
-     * @param am
-     * @param fileName
+     *
+     * @param ar for rendering audio
+     * @param am the AssetManager for loading assets
+     * @param fileName the path to the audio asset (not null)
      */
     public SoundHandleJme(AudioRenderer ar, AssetManager am, String fileName){
         if (ar == null || am == null) {

jme3-plugins/src/fbx/java/com/jme3/scene/plugins/fbx/AnimationList.java

@@ -47,17 +47,23 @@ public class AnimationList {
 
 	/**
 	 * Use in the case of multiple animation layers in FBX asset
-	 * @param name - animation name to access via {@link com.jme3.animation.AnimControl}
-	 */
+         *
+         * @param name - animation name to access via {@link com.jme3.animation.AnimControl}
+         * @param firstFrame the index of the first frame
+         * @param lastFrame the index of the last frame
+         */
 	public void add(String name, int firstFrame, int lastFrame) {
 		add(name, null, firstFrame, lastFrame);
 	}
-	
-	/**
-	 * Use in the case of multiple animation layers in FBX asset
-	 * @param name - animation name to access via {@link com.jme3.animation.AnimControl}
-	 * @param layerName - source layer
-	 */
+
+        /**
+         * Use in the case of multiple animation layers in FBX asset
+         *
+         * @param name - animation name to access via {@link com.jme3.animation.AnimControl}
+         * @param layerName - source layer
+         * @param firstFrame the index of the first frame
+         * @param lastFrame the index of the last frame
+         */
 	public void add(String name, String layerName, int firstFrame, int lastFrame) {
 		AnimInverval cue = new AnimInverval();
 		cue.name = name;

jme3-plugins/src/fbx/java/com/jme3/scene/plugins/fbx/mesh/FbxMesh.java

@@ -252,6 +252,8 @@ protected IntMap<Mesh> toJmeObject() {
 
     /**
      * Convert FBXMesh to IRMesh.
+     *
+     * @return a new IrMesh
      */
     public IrMesh toIRMesh() {
         IrMesh newMesh = new IrMesh();

jme3-plugins/src/gltf/java/com/jme3/scene/plugins/gltf/ExtensionLoader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -51,6 +51,7 @@ public interface ExtensionLoader {
      * @param extension  the content of the extension found in the element being read
      * @param input      an object containing already loaded data from the element, this is most probably a JME object
      * @return An object of the same type as input, containing the data from the input object and the eventual additional data read from the extension
+     * @throws IOException for various error conditions
      */
     Object handleExtension(GltfLoader loader, String parentName, JsonElement parent, JsonElement extension, Object input) throws IOException;
 

jme3-plugins/src/gltf/java/com/jme3/scene/plugins/gltf/GltfModelKey.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2020 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -109,7 +109,7 @@ public ExtrasLoader getExtrasLoader() {
     /**
      * Sets the ExtrasLoader for reading any extra information from the gltf file.
      *
-     * @param extrasLoader
+     * @param extrasLoader the desired loader
      */
     public void setExtrasLoader(ExtrasLoader extrasLoader) {
         this.extrasLoader = extrasLoader;

jme3-plugins/src/main/java/com/jme3/scene/plugins/IrUtils.java

@@ -102,7 +102,10 @@ private static IrPolygon[] quadToTri(IrPolygon quad) {
     }
 
     /**
-     * Applies smoothing groups to vertex normals.
+     * Applies smoothing groups to vertex normals. XXX not implemented!
+     * 
+     * @param mesh ignored
+     * @return null
      */
     public static IrMesh applySmoothingGroups(IrMesh mesh) {
         return null;
@@ -125,6 +128,11 @@ public static void toTangentsWithParity(IrMesh mesh) {
         }
     }
 
+    /**
+     * Removes low bone weights from mesh, leaving only 4 bone weights at max.
+     * 
+     * @param vertex the IrVertex to modify (not null)
+     */
     private static void trimBoneWeights(IrVertex vertex) {
         if (vertex.boneWeightsIndices == null) {
             return;
@@ -163,6 +171,8 @@ private static void trimBoneWeights(IrVertex vertex) {
 
     /**
      * Removes low bone weights from mesh, leaving only 4 bone weights at max.
+     * 
+     * @param mesh the IrMesh to modify (not null)
      */
     public static void trimBoneWeights(IrMesh mesh) {
         for (IrPolygon polygon : mesh.polygons) {
@@ -174,6 +184,8 @@ public static void trimBoneWeights(IrMesh mesh) {
 
     /**
      * Convert mesh from quads / triangles to triangles only.
+     * 
+     * @param mesh the input IrMesh (not null)
      */
     public static void triangulate(IrMesh mesh) {
         List<IrPolygon> newPolygons = new ArrayList<>(mesh.polygons.length);
@@ -200,6 +212,9 @@ public static void triangulate(IrMesh mesh) {
      * one material each.
      * 
      * Polygons without a material will be added to key = -1.
+     * 
+     * @param mesh the input IrMesh (not null)
+     * @return a new IntMap containing the resulting meshes
      */
     public static IntMap<IrMesh> splitByMaterial(IrMesh mesh) {
         IntMap<List<IrPolygon>> materialToPolyList = new IntMap<>();
@@ -239,6 +254,9 @@ public static IntMap<IrMesh> splitByMaterial(IrMesh mesh) {
 
     /**
      * Convert IrMesh to jME3 mesh.
+     *
+     * @param mesh the input IrMesh (not null)
+     * @return a new Mesh
      */
     public static Mesh convertIrMeshToJmeMesh(IrMesh mesh) {
         Map<IrVertex, Integer> vertexToVertexIndex = new HashMap<>();

jme3-plugins/src/xml/java/com/jme3/export/xml/DOMSerializer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2012 jMonkeyEngine
+ * Copyright (c) 2009-2021 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -87,7 +87,7 @@ private void escape(Writer writer, String s) throws IOException {
      * 
      * @param doc the document to serialize.
      * @param file the file to serialize to.
-     * @throws IOException
+     * @throws IOException for various error conditions
      */
     public void serialize(Document doc, File file) throws IOException {
         serialize(doc, new FileOutputStream(file));
@@ -98,7 +98,7 @@ public void serialize(Document doc, File file) throws IOException {
      * 
      * @param doc the document to serialize.
      * @param out the stream to serialize to.
-     * @throws IOException
+     * @throws IOException for various error conditions
      */
     public void serialize(Document doc, OutputStream out) throws IOException {
         Writer writer = new OutputStreamWriter(out, encoding);