Documentation software

[arthuro555]

So, it was said many times already, but the documentation system for the GDJS Runtime game engine has to be changed. Until now it was outdated, but ok. But now, the documentation begins to become more complete and includes interfaces. The current documentation is generated using JSDoc and the Jaguar template. Jaguar is not supporting interfaces, making the documentation incomplete.

The solution told by 4ian would be to switch to another documentation system like TSDoc. This can take a bit of time and the documentation needs to be made accurate as soon as possible.

I recommend switching to another template that support interfaces and is still maintained ASAP as a quick fix before thinking about another documentation software for the long term.

Any opinion on this @4ian ?

[4ian]

I would be careful about the premises: having "interfaces" is not a reason to ditch the documentation generator, especially because this is something that is not existing in other type systems (for example in Flow everything is a type - an interface is a type).
Moreover, the only "interface" that we have is for the debugger - which is low in the list of priorities of things to expose in the documentation (it's almost an internal stuff, your game should not rely on this).

I'm happy to be convinced otherwise, but I don't see anything really missing in terms of feature in JSDoc - apart from not being able to type functions with a type written like this (args) => returnType (which is really sad).

I'm afraid we're just losing a lot of precious time to switch to a "better" documentation generator (and find later that there are other issues/not maintained/not updated) while it's not the most valuable thing to do.

The most valuable thing (again, happy to be convinced otherwise) is to make all the public stuff documented (I say public. Commenting private stuff is less useful and can even expose the wrong signal by having games relying on internal stuffs, which is very dangerous) and typed (allowing better developer experience AND bug safety).
In other words, I think priority is:

1. Documenting the game engine
2. Typing the game engine
3. maybe switch to another documentation generator more suited to TypeScript.

[arthuro555]

I meant switching to another generator for the long term, after the documentation is complete. What we need to change is the JSDoc template. JSDoc itself is fine, but tha jaguar template isn't mainained since 2017 and doesn't supports interfaces. And we will also have to use interfaces for renderers that have a pixi and cocos variant.

[4ian]

If that's a matter of template for now, let's find a better documentation template that supports interfaces then :)

[arthuro555]

We could use the default one, but it's very different from the current one and could be missleading for current documentation users. Those are the main other maintained alternatives after researching for a bit:

https://github.com/braintree/jsdoc-template - Claims to be responsive
https://github.com/clenemt/docdash - Looks like lodash's Doc
https://github.com/SoftwareBrothers/better-docs - Also claims to have typescript support
https://github.com/Nijikokun/minami - Looks visually the best IMO

Is there any you find good/better?

[4ian]

I like the clean aspect of the Braintree one. It's based on minami (minami seems not to have had a release in 3 years?). Would be nice to see how it works with typescript. Actually there might be typescript plugins for jsdoc for better compatibility and allow to define types using => - those sort of things :)

…

On Sat, 18 Apr 2020, 22:42 Arthur Pacaud, ***@***.***> wrote: We could use the default one, but it's very different from the current one and could be missleading for current documentation users. Those are the main other maintained alternatives after researching for a bit: https://github.com/braintree/jsdoc-template - Claims to be responsive https://github.com/clenemt/docdash - Looks like lodash's Doc https://github.com/SoftwareBrothers/better-docs - Also claims to have typescript support https://github.com/Nijikokun/minami - Looks visually the best IMO Is there any you find good/better? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1669 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAJYRAWEMZAAYB5NM472KCLRNIGEJANCNFSM4MLN2RBQ> .

[arthuro555]

Ok, I will do a PR with Braintree then.

(minami seems not to have had a release in 3 years?)

Idk it said last commit January

[arthuro555]

Should I try other templates for you to compare? Personally I don't really like the navigations and the lack of search bar on that one.

[4ian]

Should I try other templates for you to compare? Personally I don't really like the navigations and the lack of search bar on that one.

Yes feel free to try a few templates and make screenshots :)