Help System

[loopier]

Starting this thread to discuss the help system, taking from your question on https://github.com/loopier/animatron/issues/3#issuecomment-1694634639.

In the version for G3 I started implementing an OSC-based help system. In the docs/ folder there's a /help subdirectory filled with a file for each entry. See https://github.com/loopier/animatron-godot3/tree/develop/docs.

The idea was to use this with a /help command that would post the /description text and (maybe) examples.

This means we would be using OSC as a pseudo-markdown language, which makes me think that maybe we can use GDScript's documentation comments. I wonder if there's a way to use the documentation generator Godot uses to generate the help files.

RitchTextLabel can read BBCode (see https://docs.godotengine.org/en/latest/tutorials/ui/bbcode_in_richtextlabel.html#doc-bbcode-in-richtextlabel), so we could add a documentation panel in the app. It'd be nice to be able call for /helpfrom within the editor (or OSC) and to run examples from the help file, like in SuperCollider.

One huge advantage of documenting everything in the code itself with BBCode comments is that all the information is together, allowing us to document as we code without having to switch editors. And it will be rendered in Godot's help system, too, which I think it's cool.

Should we document everything in the BBCode (in the cod comments) as if this was possible, for now, and port it later if it isn't? We can always copy-paste the rendered result (from Godot's help system), or maybe even export the help files.

If we opt for this, we should agree on the style (names of sections and formatting).

What do you think?

[totalgee]

I think that's a good idea. The only thing is that for OSC commands, they're not members, methods or functions. So we just need to decide on how we want to document those, using the capabilities provided by the GDscript help parser. I would just propose something concrete, and we can comment/refine it from there. I agree it's a good idea to have it close to the actual code, so it's more likely to be kept up to date.

[loopier]

The only thing is that for OSC commands, they're not members, methods or functions. So we just need to decide on how we want to document those,

I completely agree. I can't think of any possible solution right now. If you have an idea, just go for it.

I think that it's possible to get the arguments of a function signature, and that would be also nice to automatically put into the help output, related to the OSC address because, if I'm not mistaken, OSC arguments will be always the same as function arguments (except for aliases).

[loopier]

Document OSC messages in coreCommands dictionary.

[loopier]

Closing issue because this is also discussed at length in this other thread.