FreeType and Harfbuzz JavaDoc

[ws909]

The FreeType and Harfbuzz modules have very minimal JavaDoc. What's the state on getting this filled in?

[Spasi]

I'm afraid I've made the decision to stop adding/maintaining documentation for bindings. I posted about it in the LWJGL discord server a while back, quoting:

Maintenance of LWJGL involves a lot of different things that require hard work, but nothing comes close to creating/updating documentation for the various bindings. Even though I personally believe extensive javadoc is one of the best features LWJGL offers and writing LWJGL-based applications is a joy with it, maintenance would be 10-20x easier/faster without it. It would mean more bindings and more frequent releases.

I would accept PRs that add javadoc though.

[ws909]

Oh, that’s horrible. :( I’m not much of a dramatic person, but this is worth crying and griefing for.

[ws909]

@Spasi In LWJGL 4, is your plan to continue providing JavaDoc for the existing modules of today that have it, such as GLFW and Vulkan? Especially for Vulkan, but also much so GLFW, JavaDoc is essential. GLFW at least has a usable website, but for Vulkan? That would be absolutely terrible.

[Spasi]

Vulkan is the biggest source of stress when it comes to maintaining LWJGL, exactly because of its javadoc. There's a whole another project (lwjgl3-vulkangen) that I have to maintain just for that. Why stressful?

• The tooling is horrible (python + asciidoc).
• The source itself is broken in many different ways and I have to patch it to even be able to get working documentation out of it. Every few Vulkan versions something new breaks and hunting down the offending asciidoc (usually a typo or a stupid whitespace issue) is a nightmare.
• Worst of all, they keep refactoring Vulkan-Docs (good for them) and breaking downstream users like me. I've lost count how many times since Vulkan was released. See the changelog for Vulkan 1.3.241 for the latest one.

As I wrote above, javadoc in LWJGL is an amazing feature and I'm sad to see it go too. However, I'm a solo developer maintaining a huge codebase in my free time and my free time is too precious right now to have to deal with javadoc. I'm 40 with a very busy family and career life. As long as no one else is helping, the best I can do is LWJGL without javadoc in bindings.

[ws909]

I understand that you have other responsibilities and interests to attend to, and that this is a source of stress, but what would it take for this to be a continued effort in LWJGL 4? I have not yet had the time to look into LWJGL-Vulkangen and these stress sources which you point at.

You say that you will accept PRs for JavaDoc, but this is not straightforward and easy to work with if the entire supporting projects are discontinued and shut down.

[mva]

For documentation, I find myself usually relying on Vulkan's HTML version. It provides more context (which I often need for my own understanding), and its "Search:" box to jump into the text is ok-ish. For values of constants or to see them in context, I page through `vk.xml`. While I see value in the Vulkan javadocs, the value of the bare bindings is immeasurably higher. Given the way Vulkan evolves over time, I do not expect any of the stress points you mention to go away in the near or medium future. My vote would be to drop the javadoc because of its cost, and refer to the upstream documentation instead. Message ID: ***@***.***>

…

[ws909]

Well, this just goes to show that we have different preferences. I rely on the JavaDoc, and find the HTML documentation cumbersome, slow, and too crowded. The JavaDoc suits my needs (almost) perfectly. Every now and then, I do resort to the HTML documentation, but that's rare. It just cannot provide the same easy access that the JavaDoc does; inline in the IDE, always ready for display at a mouse sweep or keystroke.