[RFC] The future of Documentation in KubeJS

[MaxNeedsSnacks]

Introduction

Recently, there has been quite an uptick of support requests related to a lack of proper documentation in large parts of KubeJS.
While creating docs for end users using KubeJS in the form of typescript typings or at least a wiki covering the mod's base functionality has definitely always been on our mind (see #10 and #53), it's taken a lot longer than expected due to feature requests, bug fixes and other projects taking up too much time.

KubeJS is essentially a three-man project, with Lat working on the bulk of the mod's actual codebase and addons (like recipe addons, mod integration with the FTB suite of mods, and so on), and Dan and myself working on the backend framework that makes this mod work multiplatform. None of us are good at writing docs ourselves, and as the feature set of KubeJS constantly keeps changing, our goal has pretty much always been to auto-generate things where possible for KubeJS' documentation.

Make yourself heard!

As docs are definitely going to be quite important for this project going forward, especially as we slowly migrate away from wrapper classes towards more direct interactions with native Minecraft and mod objects, I'd like to throw a couple of suggestions your way that we've heard over the last couple of months, as well as their relative strengths and weaknesses that I have personally discovered. Your feedback will be absolutely paramount here, as we're pretty unlikely to change our approach to docs again once it's been set in stone, at least for the foreseeable future.

Typescript typings

First off, let's address the elephant in the room: Typescript typings have been a requested feature for a long time now (in fact, that 1 year old GitHub issue isn't even the first instance of it being requested), and for good reason: They integrate directly with most IDEs used for scripting (Atom, VSCode, WebStorm), and offer a fast and reliable overview about the inner workings of whatever you are working with. There's even an automated tool to help with generating them from Java code, however there are still a couple of problems with this approach that may make it suboptimal. First off, concerning said tool, you have to manually specify each and every class name you want to generate typings for, which can be a bit of a hassle for a project with the size of KubeJS. That aside, these TypeScript typings are static, meaning we'd have to regenerate them each time we made an internal change. Another potential problem is that end users would have to download and declare these typings themselves, as we don't benefit from the same auto-detection as, say, Node.JS modules. Because of this, I'd say that while typings are overall definitely a desirable goal, they should not be our only solution for docs.

Dynamic in-game docs (á la Aurora)

As I've said in the introduction, auto-generating docs has pretty much always been the go-to for us when it came to documenting KubeJS. In 1.12, we tried to achieve this by using a mod called Aurora, a local web server that would dynamically generate basic Javadoc-style documentation for anything you would ever want to use KubeJS for. That approach, however, also had a lot of weaknesses on its own, for example, parameter names don't exist at runtime, so you'd have methods with ambiguous auto-generated parameter names like var1, var2, ... that didn't carry much real-world meaning. To make matters worse, certain wrapper methods like Ingredient.of take in generic Objects as parameters in order to try and wrap these objects to their target types, which combined with the previous issue made the docs... not very expressive at all. (again, think of seeing a method like event.addPulverizer(Object var1, Object var2, flaot var3, int var4) in your auto-generated docs). On top of all of this, Aurora was a web server, which meant it had to be bound to a port, which can be quite suboptimal in some cases, e.g. for people who are trying to host a server with a hosting company that limits them to a specific IP / port. That and having an entire web server be hosted on your machine just for documentation can be quite a bit of a turn-off, to say the least.

Static in-game docs (/kubejs gen_docs)

Another approach Lat himself actually suggested to mitigate that web server part was to have a command called gen_docs. Users could use this to generate a json file, which they would then submit to a site on Lat's own server, which would in turn then display the appropriate docs for them automatically. While this approach is definitely better than using something like Aurora, it still suffers from the same problems of having to be generated at runtime: It's not particularly performant, there's no real "validation" going on in the background, and the styling can be quite.. suboptimal, especially with the obfuscated Minecraft classes thrown in the mix (on Fabric, these get turned into "intermediary" class names like class_15032, which again, will look pretty bad and confusing to end users (class_15032.method_5964(class_48 var1, class_937 var2) and other horribleness awaits!)

The ol' reliable (just make a wiki 4Head)

Finally, we come to what might be the obvious solution to some: Creating and maintaining a proper manual wiki for KubeJS that would offer help for most things regular users could want, as well as offering manually curated examples for some of the more "advanced" things you can do with the mod. This is the one solution that's basically always proven itself to work, and in fact, we already have a Wiki for a lot of things here, however, maintaining it as the small group of modders that we are has become hell, to put it bluntly. Thus, if we do decide to go with this, it would definitely be worthwhile to make the whole thing more community-driven, both to lighten the workload on the core team a little so we can keep working on the actual mod, and to hopefully improve the quality at which things are explained to pack devs and end users; it's hard to get out of that "programmer mindset" that people will just look things up in the source if they have to, and you can often tell this is the case by the lackluster documentation that actually reaches the users in the end.

Bonus round (other approaches and why they probably wouldn't work that well)

• Javadoc: Generally not a bad idea, but it would suffer from the same problems as maintaining a proper Wiki and we can't exactly add Javadocs to native Minecraft classes, unfortunately
• Auto-generating a wiki: Would suffer from similar problems as the other auto-genned approaches, plus it would need a lot of manual curating or otherwise it would be just as confusing as the in-game docs
• Patchouli: ...no. Just... no. (needs an in-game item, would still need actual documentation to be written or generated, adds yet another dependency to KubeJS)

And that's about it! Feel free to leave your feedback down below, as that's really the only way that we can tell whether what we're doing here is actually beneficial to the people that end up using our mods or not ^^

[benbenlaw]

i feel like a wiki with at least one example of a certain requested recipe or change would be helpful. For people like myself learning how to code JS having a visual aid is so benifical for me and seeing the limitations of the codes im using will be a great help. Also maybe a place to upload and view user made code and a explaination on what it does.

[LatvianModder]

Place to upload code snippets is sort of planned. We just need to figure out moderation etc, but it should be somewhat easy. with tags etc

[ghost]

I'd like to echo what @benbenlaw says here. Having a visual aid in the form of example for different recipes and changes (including user-submitted snippets) would be extremely beneficial.

[pm065]

100% the public wiki and user submitted snippet section. (Though you'd have to make sure it doesn't turn out the same way as the now-deleted TeamAbnormals wiki did :p)

I just toiled for three days trying to make a recipe generator for wooden items without plagiarizing from Enigmatica (I haven't used JS before, okay?). I wouldn't want anyone else to go through that; even if it is a little messy, I'd immediately upload the three scripts. (Also, a public wiki would probably have halved the time the scripts took to make.)

That brings me to something else; could the snippet-uploading place have a way to suggest changes to other's snippets? So others could refine and improve the bits of code, to make sure it isn't teaching newcomers bad practise.

[jexom]

Considering that basically any approach would require either regeneration or generation at runtime, then apart from Typescript typings I think a wiki with examples is a way to go.
That way typings would provide the user with "what you can do" and the wiki would provide the "how you can do".

[kiontupper]

I started work on a runtime TypeScript binding generator that generates bindings when the scripts load. The idea is you load the game and a world once, and a workspace will appear in the scripts folders that will work with editors like VSCode. Though this is mainly for the purposes of error checking and autocomplete, since JavaDoc comments aren't accessible at runtime.

[Hunter19823]

As for the topic of Aurora documentation, I believe there is an option to fix the "ambiguous auto-generated parameter names like var1, var2, ...". By compiling a mod with the -parameters javac option, parameter names should be provided. Alternatively, a mod compiles with the -g
compiler option, parameter names should be provided as well.

Additionally, I believe a hybrid between aurora and static in-game docs can be achieved as well, by generating documentation on a jar by jar basis. Aka you provide the mods you are using, perhaps via manifest.json for curse forge, or by uploading a jar file itself.
Then using java reflection, you generate all the HTML files, or even a single HTML file with multiple JSON files to load the class data from.
Thus removing the need for a web server as well as making the documents available offline.

Another suggestion:
Moving from aurora to GitHub pages.
Incorporating both generated documentation and example scripts.
Taking examples from the Expression 2 wiki: https://github.com/wiremod/wire/wiki
Using GitHub pages on a mod by mod basis instead of a datatype by datatype basis. Maybe even on a package by package basis.
It might only be limited to KubeJS classes, but possibly having the page URL be something like
https://github.com/KubeJS-Mods/KubeJS/wiki/projectid-modversion
or
https://github.com/KubeJS-Mods/KubeJS/wiki/dev.latvian.kubejs.text.Text
Where each page contains all classes for that mod with an index at the top with the ability to link to a specific class/method.
These would have to be manually curated, and can only contain a gigabyte of pages.
But a wiki with even just KubeJS pages would be helpful enough so that people don't have to go digging through source code every 5 minutes.
Additionally, since you would generate these pages separately from the mod, you can compile with the -parameter option and even link directly to the KubeJS source code from the page.

On the topic of java docs:
The bulk of the work is actually adding the actual doc comments.
I would be willing to help do a lot of the grunt work to get that off the ground.
If the limiting factor is maintaining that JavaDoc, I suggest adding annotations or putting comments whenever something needs proper documentation still or has been changed recently and the JavaDoc might not be accurate.
The thought process of having annotations is that you can pass the responsibility of documenting a method you just made/changed to someone else. Preventing your workflow from being interrupted until someone properly documents things.

tl;dr: I think Example scripts + Auto Generation of Documentation in a centralized location will be the most effective approach.

[LatvianModder]

I made this a long time ago, for github hosted, PR enocouraged docs that would support examples but never finished it. so this is what official docs will look like https://github.com/KubeJS-Mods/KubeJS-Docs/blob/main/docs/string.jdoc They would be reformatted and hosted on https://wiki.kubejs.com/ Typescript index file would also be auto-generated from this

[SwanX1]

I've started making KubeJS typings for my own personal use, just add some random stuff here and there. Never bothered to upload them to GitHub or anywhere else, as I didn't think they'd be good enough for others to use 😅 The worst part is reading the actual code on what gets parsed and how it gets parsed. I'd actually support and possibly contribute to manually-made typings. I know this solution isn't the greatest but it's what I propose.

[pauliesnug]

Is there any update on this? I saw ProbeJS, is it still actively maintained?

[ChiefArug]

There is a new wiki being created, the git repo is at https://github.com/KubeJS-Mods/wiki and its linked somewhere on the https://kubejs.com website.
ProbeJS is also being actively maintained.