docs: add package-info links to useful resources

doc/notes/3.4.0.md

@@ -6,6 +6,15 @@ This build includes the following changes:
 
 #### Bindings
 
+LWJGL bindings no longer include API documentation in javadoc form. What remains: 
+
+* Native struct definitions.
+* Native function signatures for downcalls (new in 3.4.0) and upcalls.
+* The `package-info` javadoc in each module now also includes links to useful resources, such as: 
+  - The official API documentation.
+  - The official source repository.
+  - Guides, tutorials, SDKs, etc.
+
 #### Improvements
 
 #### Fixes

modules/lwjgl/assimp/src/generated/java/org/lwjgl/assimp/package-info.java

@@ -14,6 +14,13 @@
  * <p>Written in C++, it is available under a liberal BSD license. Assimp loads all input model formats into one straightforward data structure for further
  * processing. This feature set is augmented by various post processing tools, including frequently-needed operations such as computing normal and tangent
  * vectors.</p>
+ * 
+ * <h3>Resources</h3>
+ * 
+ * <ul>
+ * <li><a href="https://assimp-docs.readthedocs.io/en/latest/">Documentation</a></li>
+ * <li><a href="https://github.com/assimp/assimp">Source Repository</a></li>
+ * </ul>
  */
 @org.jspecify.annotations.NullMarked
 package org.lwjgl.assimp;

modules/lwjgl/bgfx/src/generated/java/org/lwjgl/bgfx/package-info.java

@@ -5,10 +5,7 @@
  */
 
 /**
- * Contains bindings to the <a href="https://github.com/bkaradzic/bgfx">bgfx</a> library.
- * 
- * <p>The bgfx documentation can be found online <a href="https://bkaradzic.github.io/bgfx/">here</a>. The API reference is available
- * <a href="https://bkaradzic.github.io/bgfx/bgfx.html">here</a>.</p>
+ * Contains bindings to the <a href="https://bkaradzic.github.io/bgfx/">bgfx</a> library.
  * 
  * <p>Starting with LWJGL 3.2.1, builds of the bgfx tools are available for download via the LWJGL site's <a href="https://www.lwjgl.org/browse">file
  * browser</a>. These tools are:</p>
@@ -22,6 +19,13 @@
  * 
  * <p>The binaries are built from source, at the corresponding commit that was used to build the bgfx library. For example, the latest Windows x64 version of
  * shaderc can be found under {@code nightly/windows/x64/bgfx-tools/}.</p>
+ * 
+ * <h3>Resources</h3>
+ * 
+ * <ul>
+ * <li><a href="https://bkaradzic.github.io/bgfx/bgfx.html">Documentation</a></li>
+ * <li><a href="https://github.com/bkaradzic/bgfx">Source Repository</a></li>
+ * </ul>
  */
 @org.jspecify.annotations.NullMarked
 package org.lwjgl.bgfx;

modules/lwjgl/cuda/src/generated/java/org/lwjgl/cuda/package-info.java

@@ -11,6 +11,12 @@
  * 
  * <p>Until these bindings are sufficiently tested, this API should be considered unstable. Also, bindings to more (and eventually, all) CUDA Toolkit
  * libraries will be added in the near future.</p>
+ * 
+ * <h3>Resources</h3>
+ * 
+ * <ul>
+ * <li><a href="https://docs.nvidia.com/cuda/">Documentation</a></li>
+ * </ul>
  */
 @org.jspecify.annotations.NullMarked
 package org.lwjgl.cuda;

modules/lwjgl/egl/src/generated/java/org/lwjgl/egl/package-info.java

@@ -9,8 +9,12 @@
  * the underlying native platform window system. It handles graphics context management, surface/buffer binding and rendering synchronization and enables
  * high-performance, accelerated, mixed-mode 2D and 3D rendering using other Khronos APIs.
  * 
- * <p>The <a href="https://www.khronos.org/registry/EGL/">Khronos EGL registry</a> is a useful online resource that contains the EGL specification, as well
- * as specifications of EGL extensions.</p>
+ * <h3>Resources</h3>
+ * 
+ * <ul>
+ * <li><a href="https://registry.khronos.org/EGL/">Documentation</a></li>
+ * <li><a href="https://github.com/KhronosGroup/EGL-Registry">Source Repository</a></li>
+ * </ul>
  */
 @org.jspecify.annotations.NullMarked
 package org.lwjgl.egl;

modules/lwjgl/freetype/src/generated/java/org/lwjgl/util/freetype/package-info.java

@@ -9,6 +9,13 @@
  * 
  * <p>It is written in C, designed to be small, efficient, highly customizable, and portable while capable of producing high-quality output (glyph images) of
  * most vector and bitmap font formats.</p>
+ * 
+ * <h3>Resources</h3>
+ * 
+ * <ul>
+ * <li><a href="https://freetype.org/freetype2/docs/documentation.html">Documentation</a></li>
+ * <li><a href="https://github.com/freetype/freetype">Source Repository</a></li>
+ * </ul>
  */
 @org.jspecify.annotations.NullMarked
 package org.lwjgl.util.freetype;

modules/lwjgl/glfw/src/generated/java/org/lwjgl/glfw/package-info.java

@@ -19,6 +19,13 @@
  * <p>Applications that cannot function with the above limitation may set {@link org.lwjgl.system.Configuration#GLFW_LIBRARY_NAME GLFW_LIBRARY_NAME} to the
  * value {@code "glfw_async"}. This will instruct LWJGL to load an alternative GLFW build that dispatches Cocoa calls to the main thread in blocking mode.
  * The other window toolkit must be initialized (e.g. with AWT's {@code Toolkit.getDefaultToolkit()}) before {@link org.lwjgl.glfw.GLFW#glfwInit Init} is called.</p>
+ * 
+ * <h3>Resources</h3>
+ * 
+ * <ul>
+ * <li><a href="https://www.glfw.org/documentation.html">Documentation</a></li>
+ * <li><a href="https://github.com/glfw/glfw">Source Repository</a></li>
+ * </ul>
  */
 @org.jspecify.annotations.NullMarked
 package org.lwjgl.glfw;

modules/lwjgl/harfbuzz/src/generated/java/org/lwjgl/util/harfbuzz/package-info.java

@@ -9,6 +9,13 @@
  * 
  * <p>Using the HarfBuzz library allows programs to convert a sequence of Unicode input into properly formatted and positioned glyph output — for any writing
  * system and language.</p>
+ * 
+ * <h3>Resources</h3>
+ * 
+ * <ul>
+ * <li><a href="https://harfbuzz.github.io/user-manual.html">Documentation</a></li>
+ * <li><a href="https://github.com/harfbuzz/harfbuzz">Source Repository</a></li>
+ * </ul>
  */
 @org.jspecify.annotations.NullMarked
 package org.lwjgl.util.harfbuzz;

modules/lwjgl/hwloc/src/generated/java/org/lwjgl/util/hwloc/package-info.java

@@ -17,6 +17,13 @@
  * 
  * <p>hwloc may also help many applications just by providing a portable CPU and memory binding API and a reliable way to find out how many cores and/or
  * hardware threads are available.</p>
+ * 
+ * <h3>Resources</h3>
+ * 
+ * <ul>
+ * <li><a href="https://www.open-mpi.org/projects/hwloc/doc/">Documentation</a></li>
+ * <li><a href="https://github.com/open-mpi/hwloc">Source Repository</a></li>
+ * </ul>
  */
 @org.jspecify.annotations.NullMarked
 package org.lwjgl.util.hwloc;

modules/lwjgl/jemalloc/src/generated/java/org/lwjgl/system/jemalloc/package-info.java

@@ -8,9 +8,6 @@
  * Contains bindings to the <a href="https://jemalloc.net/">jemalloc</a> library. jemalloc is a general purpose malloc implementation that emphasizes
  * fragmentation avoidance and scalable concurrency support.
  * 
- * <p>The jemalloc documentation can be found <a href="https://jemalloc.net/jemalloc.3.html">here</a>. The jemalloc
- * <a href="https://github.com/jemalloc/jemalloc/wiki">wiki</a> also contains useful information.</p>
- * 
  * <p>The jemalloc shared library that comes with LWJGL is configured with:</p>
  * 
  * <ul>
@@ -27,6 +24,13 @@
  * 
  * <p>Dynamic configuration (for enabled features) is also possible, using either the {@code MALLOC_CONF} environment variable or the
  * <a href="https://jemalloc.net/jemalloc.3.html#mallctl_namespace">MALLCTL NAMESPACE</a> and the {@code mallctl*} functions.</p>
+ * 
+ * <h3>Resources</h3>
+ * 
+ * <ul>
+ * <li><a href="https://jemalloc.net/jemalloc.3.html">Documentation</a></li>
+ * <li><a href="https://github.com/jemalloc/jemalloc">Source Repository</a></li>
+ * </ul>
  */
 @org.jspecify.annotations.NullMarked
 package org.lwjgl.system.jemalloc;

modules/lwjgl/ktx/src/generated/java/org/lwjgl/util/ktx/package-info.java

@@ -11,6 +11,14 @@
  * <p>The LWJGL bindings support the KTX encoding functionality, but its presence is optional. Applications may choose to deploy the read-only version of the
  * KTX library ({@code ktx_read}) and the bindings will work. The {@link org.lwjgl.system.Configuration#KTX_LIBRARY_NAME KTX_LIBRARY_NAME} option can be
  * used to change the loaded library.</p>
+ * 
+ * <h3>Resources</h3>
+ * 
+ * <ul>
+ * <li><a href="https://github.com/KhronosGroup/3D-Formats-Guidelines/blob/main/KTXDeveloperGuide.md">Developer Guide</a></li>
+ * <li><a href="https://registry.khronos.org/KTX/specs/2.0/ktxspec.v2.html">Specification</a></li>
+ * <li><a href="https://github.com/KhronosGroup/KTX-Software">Source Repository</a></li>
+ * </ul>
  */
 @org.jspecify.annotations.NullMarked
 package org.lwjgl.util.ktx;

modules/lwjgl/libdivide/src/generated/java/org/lwjgl/util/libdivide/package-info.java

@@ -4,7 +4,16 @@
  * MACHINE GENERATED FILE, DO NOT EDIT
  */
 
-/** Contains bindings to <a href="https://libdivide.com/">libdivide</a>. */
+/**
+ * Contains bindings to <a href="https://libdivide.com/">libdivide</a>.
+ * 
+ * <h3>Resources</h3>
+ * 
+ * <ul>
+ * <li><a href="https://libdivide.com/documentation.html">Documentation</a></li>
+ * <li><a href="https://github.com/ridiculousfish/libdivide">Source Repository</a></li>
+ * </ul>
+ */
 @org.jspecify.annotations.NullMarked
 package org.lwjgl.util.libdivide;
 

modules/lwjgl/llvm/src/generated/java/org/lwjgl/llvm/package-info.java

@@ -7,14 +7,17 @@
 /**
  * Contains bindings to <a href="https://llvm.org/">LLVM</a>, a collection of modular and reusable compiler and toolchain technologies.
  * 
- * <h3>UNSTABLE API</h3>
- * 
- * <p>Until these bindings are sufficiently tested, this API should be considered unstable.</p>
- * 
  * <h3>BINDINGS ONLY</h3>
  * 
  * <p>LWJGL does not currently include pre-built LLVM/Clang binaries. The user must download or build LLVM separately and use
  * {@link org.lwjgl.system.Configuration Configuration} to point LWJGL to the appropriate binaries.</p>
+ * 
+ * <h3>Resources</h3>
+ * 
+ * <ul>
+ * <li><a href="https://llvm.org/docs/">Documentation</a></li>
+ * <li><a href="https://github.com/llvm/llvm-project">Source Repository</a></li>
+ * </ul>
  */
 @org.jspecify.annotations.NullMarked
 package org.lwjgl.llvm;

modules/lwjgl/lmdb/src/generated/java/org/lwjgl/util/lmdb/package-info.java

@@ -13,81 +13,12 @@
  * fully transactional with full ACID semantics, and when the memory map is read-only, the database integrity cannot be corrupted by stray pointer writes
  * from application code.</p>
  * 
- * <p>The library is fully thread-aware and supports concurrent read/write access from multiple processes and threads. Data pages use a copy-on-write
- * strategy so no active data pages are ever overwritten, which also provides resistance to corruption and eliminates the need of any special recovery
- * procedures after a system crash. Writes are fully serialized; only one write transaction may be active at a time, which guarantees that writers can
- * never deadlock. The database structure is multi-versioned so readers run with no locks; writers cannot block readers, and readers don't block writers.</p>
- * 
- * <p>Unlike other well-known database mechanisms which use either write-ahead transaction logs or append-only data writes, LMDB requires no maintenance
- * during operation. Both write-ahead loggers and append-only databases require periodic checkpointing and/or compaction of their log or database files
- * otherwise they grow without bound. LMDB tracks free pages within the database and re-uses them for new write operations, so the database size does not
- * grow without bound in normal use.</p>
- * 
- * <p>The memory map can be used as a read-only or read-write map. It is read-only by default as this provides total immunity to corruption. Using read-write
- * mode offers much higher write performance, but adds the possibility for stray application writes thru pointers to silently corrupt the database. Of
- * course if your application code is known to be bug-free (...) then this is not an issue.</p>
- * 
- * <h3>Restrictions/caveats (in addition to those listed for some functions)</h3>
- * 
- * <ul>
- * <li>Only the database owner should normally use the database on BSD systems or when otherwise configured with {@code MDB_USE_POSIX_SEM}. Multiple users
- * can cause startup to fail later, as noted above.</li>
- * <li>There is normally no pure read-only mode, since readers need write access to locks and lock file. Exceptions: On read-only filesystems or with the
- * {@link org.lwjgl.util.lmdb.LMDB#MDB_NOLOCK NOLOCK} flag described under {@link org.lwjgl.util.lmdb.LMDB#mdb_env_open env_open}.</li>
- * <li>An LMDB configuration will often reserve considerable unused memory address space and maybe file size for future growth. This does not use actual
- * memory or disk space, but users may need to understand the difference so they won't be scared off.</li>
- * <li>By default, in versions before 0.9.10, unused portions of the data file might receive garbage data from memory freed by other code. (This does not
- * happen when using the {@link org.lwjgl.util.lmdb.LMDB#MDB_WRITEMAP WRITEMAP} flag.) As of 0.9.10 the default behavior is to initialize such memory before writing to the data file. Since there
- * may be a slight performance cost due to this initialization, applications may disable it using the {@link org.lwjgl.util.lmdb.LMDB#MDB_NOMEMINIT NOMEMINIT} flag. Applications handling sensitive
- * data which must not be written should not use this flag. This flag is irrelevant when using {@link org.lwjgl.util.lmdb.LMDB#MDB_WRITEMAP WRITEMAP}.</li>
- * <li>A thread can only use one transaction at a time, plus any child transactions. Each transaction belongs to one thread. The {@link org.lwjgl.util.lmdb.LMDB#MDB_NOTLS NOTLS} flag changes this
- * for read-only transactions.</li>
- * <li>Use an {@code MDB_env*} in the process which opened it, without {@code fork()}ing.</li>
- * <li>Do not have open an LMDB database twice in the same process at the same time. Not even from a plain {@code open()} call - {@code close()}ing it
- * breaks {@code flock()} advisory locking.</li>
- * <li>Avoid long-lived transactions. Read transactions prevent reuse of pages freed by newer write transactions, thus the database can grow quickly.
- * Write transactions prevent other write transactions, since writes are serialized.</li>
- * <li>Avoid suspending a process with active transactions. These would then be "long-lived" as above. Also read transactions suspended when writers
- * commit could sometimes see wrong data.</li>
- * </ul>
- * 
- * <p>...when several processes can use a database concurrently:</p>
+ * <h3>Resources</h3>
  * 
  * <ul>
- * <li>Avoid aborting a process with an active transaction. The transaction becomes "long-lived" as above until a check for stale readers is performed or
- * the lockfile is reset, since the process may not remove it from the lockfile.
- * 
- * <p>This does not apply to write transactions if the system clears stale writers, see above.</p></li>
- * <li>If you do that anyway, do a periodic check for stale readers. Or close the environment once in a while, so the lockfile can get reset.</li>
- * <li>Do not use LMDB databases on remote filesystems, even between processes on the same host. This breaks {@code flock()} on some OSes, possibly memory
- * map sync, and certainly sync between programs on different hosts.</li>
- * <li>Opening a database can fail if another process is opening or closing it at exactly the same time.</li>
+ * <li><a href="http://www.lmdb.tech/doc/">Documentation</a></li>
+ * <li><a href="https://github.com/LMDB/lmdb">Source Repository</a></li>
  * </ul>
- * 
- * <h3>Reader Lock Table</h3>
- * 
- * <p>Readers don't acquire any locks for their data access. Instead, they simply record their transaction ID in the reader table. The reader mutex is needed
- * just to find an empty slot in the reader table. The slot's address is saved in thread-specific data so that subsequent read transactions started by the
- * same thread need no further locking to proceed.</p>
- * 
- * <p>If {@link org.lwjgl.util.lmdb.LMDB#MDB_NOTLS NOTLS} is set, the slot address is not saved in thread-specific data.</p>
- * 
- * <p>No reader table is used if the database is on a read-only filesystem, or if {@link org.lwjgl.util.lmdb.LMDB#MDB_NOLOCK NOLOCK} is set.</p>
- * 
- * <p>Since the database uses multi-version concurrency control, readers don't actually need any locking. This table is used to keep track of which readers
- * are using data from which old transactions, so that we'll know when a particular old transaction is no longer in use. Old transactions that have
- * discarded any data pages can then have those pages reclaimed for use by a later write transaction.</p>
- * 
- * <p>The lock table is constructed such that reader slots are aligned with the processor's cache line size. Any slot is only ever used by one thread. This
- * alignment guarantees that there will be no contention or cache thrashing as threads update their own slot info, and also eliminates any need for
- * locking when accessing a slot.</p>
- * 
- * <p>A writer thread will scan every slot in the table to determine the oldest outstanding reader transaction. Any freed pages older than this will be
- * reclaimed by the writer. The writer doesn't use any locks when scanning this table. This means that there's no guarantee that the writer will see the
- * most up-to-date reader info, but that's not required for correct operation - all we need is to know the upper bound on the oldest reader, we don't care
- * at all about the newest reader. So the only consequence of reading stale information here is that old pages might hang around a while longer before
- * being reclaimed. That's actually good anyway, because the longer we delay reclaiming old pages, the more likely it is that a string of contiguous pages
- * can be found after coalescing old pages from many old transactions together.</p>
  */
 @org.jspecify.annotations.NullMarked
 package org.lwjgl.util.lmdb;

modules/lwjgl/lz4/src/generated/java/org/lwjgl/util/lz4/package-info.java

@@ -8,6 +8,12 @@
  * Contains bindings to <a href="https://lz4.org/">LZ4</a>, a lossless compression algorithm, providing compression speed &gt; 500 MB/s per core,
  * scalable with multi-cores CPU. It features an extremely fast decoder, with speed in multiple GB/s per core, typically reaching RAM speed limits on
  * multi-core systems.
+ * 
+ * <h3>Resources</h3>
+ * 
+ * <ul>
+ * <li><a href="https://github.com/lz4/lz4">Source Repository</a></li>
+ * </ul>
  */
 @org.jspecify.annotations.NullMarked
 package org.lwjgl.util.lz4;

modules/lwjgl/meow/src/generated/java/org/lwjgl/util/meow/package-info.java

@@ -4,7 +4,15 @@
  * MACHINE GENERATED FILE, DO NOT EDIT
  */
 
-/** Contains bindings to <a href="https://github.com/cmuratori/meow_hash">Meow hash</a>, an extremely fast non-cryptographic hash. */
+/**
+ * Contains bindings to <a href="https://mollyrocket.com/meowhash">Meow hash</a>, an extremely fast non-cryptographic hash.
+ * 
+ * <h3>Resources</h3>
+ * 
+ * <ul>
+ * <li><a href="https://github.com/cmuratori/meow_hash">Source Repository</a></li>
+ * </ul>
+ */
 @org.jspecify.annotations.NullMarked
 package org.lwjgl.util.meow;
 

modules/lwjgl/nuklear/src/generated/java/org/lwjgl/nuklear/package-info.java

@@ -5,14 +5,18 @@
  */
 
 /**
- * Bindings to the <a href="https://github.com/vurtun/nuklear">Nuklear</a> library.
+ * Bindings to the <a href="https://immediate-mode-ui.github.io/Nuklear/">Nuklear</a> library.
  * 
  * <p>A minimal state immediate mode graphical user interface single header toolkit written in ANSI C and licensed under public domain. It was designed as a
  * simple embeddable user interface for application and does not have any dependencies, a default renderbackend or OS window and input handling but
  * instead provides a very modular library approach by using simple input state for input and draw commands describing primitive shapes as output. So
  * instead of providing a layered library that tries to abstract over a number of platform and render backends it only focuses on the actual UI.</p>
  * 
- * <p>Developed by Micha Mettke.</p>
+ * <h3>Resources</h3>
+ * 
+ * <ul>
+ * <li><a href="https://github.com/Immediate-Mode-UI/Nuklear">Source Repository</a></li>
+ * </ul>
  */
 @org.jspecify.annotations.NullMarked
 package org.lwjgl.nuklear;

modules/lwjgl/odbc/src/generated/java/org/lwjgl/odbc/package-info.java

@@ -5,7 +5,7 @@
  */
 
 /**
- * Contains bindings to <a href="https://docs.microsoft.com/en-us/sql/odbc/microsoft-open-database-connectivity-odbc">ODBC</a>.
+ * Contains bindings to <a href="https://learn.microsoft.com/en-us/sql/odbc/microsoft-open-database-connectivity-odbc">ODBC</a>.
  * 
  * <p>The Microsoft Open Database Connectivity (ODBC) interface is a C programming language interface that makes it possible for applications to access data
  * from a variety of database management systems (DBMSs). ODBC is a low-level, high-performance interface that is designed specifically for relational
@@ -14,6 +14,12 @@
  * <p>The ODBC interface allows maximum interoperability — an application can access data in diverse DBMSs through a single interface. Moreover, that
  * application will be independent of any DBMS from which it accesses data. Users of the application can add software components called drivers, which
  * interface between an application and a specific DBMS.</p>
+ * 
+ * <h3>Resources</h3>
+ * 
+ * <ul>
+ * <li><a href="https://learn.microsoft.com/en-us/sql/odbc/reference/odbc-programmer-s-reference">Documentation</a></li>
+ * </ul>
  */
 @org.jspecify.annotations.NullMarked
 package org.lwjgl.odbc;