Refactor: Torus Mesh optimization + javadoc

[capdevon]

This PR significantly improves the Torus mesh by:

• Refining vertex and index generation logic.
• Removing the unused vertexIndex variable in generateGeometryData.
• Adding thorough Javadoc comments for all methods and fields.
• Introducing validation for constructor parameters to prevent invalid mesh creation. These changes enhance code readability, maintainability, and robustness.`

[github-actions]

🖼️ Screenshot tests have failed.

The purpose of these tests is to ensure that changes introduced in this PR don't break visual features. They are visual unit tests.

📄 Where to find the report:

• Go to the (failed run) > Summary > Artifacts > screenshot-test-report
• Download the zip and open jme3-screenshot-tests/build/reports/ScreenshotDiffReport.html

⚠️ If you didn't expect to change anything visual:
Fix your changes so the screenshot tests pass.

✅ If you did mean to change things:
Review the replacement images in jme3-screenshot-tests/build/changed-images to make sure they really are improvements and then replace and commit the replacement images at jme3-screenshot-tests/src/test/resources.

✨ If you are creating entirely new tests:
Find the new images in jme3-screenshot-tests/build/changed-images and commit the new images at jme3-screenshot-tests/src/test/resources.

Note; it is very important that the committed reference images are created on the build pipeline, locally created images are not reliable. Similarly tests will fail locally but you can look at the report to check they are "visually similar".

See https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-screenshot-tests/README.md for more information

Contact @richardTingle (aka richtea) for guidance if required

[capdevon]

@yaRnMcDonuts @richardTingle
Hi guys, can you help me understand why this PR doesn't pass the test?

[richardTingle]

The tests that fail are one that uses the Torus so something has changed (although the difference is pretty subtle). Are the meshes you generate after your change identical to the ones before you change?

[richardTingle]

You have subtle differences in your position and normal data. I used this within the torus class to print them out

    System.out.println("Position: " + Arrays.toString(BufferUtils.getFloatArray(fpb)));
    System.out.println();
    System.out.println("normals: " + Arrays.toString(BufferUtils.getFloatArray(fnb)));

For example position index 14 is 0.0 in master but 2.1855694E-8 in your branch

[capdevon]

The number $2.1855694 \times 10^{-8}$ is a very small number, meaning it tends to zero. Therefore, the difference between $0.0f$ and $2.1855694 \times 10^{-8}$ is also very small, and not considered a large difference.

[richardTingle]

Well yes, it is a very small difference. Why has it changed at all? Isn't this supposed to just be a refactor?

(If it used to be 2.1855694E-8 and was now 0 I might say that was an improvement, but it's the other way round)

If you really really wanted to do this you'd need to update the reference images (as the bot explained) but unexpected numerical changes worries me a bit. What's the reason for introducing this change?

[capdevon]

The last 85 PRs aim to enhance the jme3-core module through optimization, feature additions, duplication removal, stabilization, and comprehensive Javadoc implementation. My work isn't a critique of the original authors; I respect their contributions and am confident they did their best. However, some areas have become complex and challenging to read, often lacking comments or containing 'magic numbers.' I've used various analysis tools to identify and address critical issues.

Regarding this PR, it significantly simplifies the original code. While there might be minor differences in decimal values compared to the old algorithm—which duplicated initial vertices for loop closure and texture smoothing—I believe the overall result is a substantial improvement. So I revert the setGeometryData() method. I'm satisfied with the current implementation and suggest we proceed with merging this PR to allow me to focus on testing the remaining PRs.