On Documentation

[loopier]

Command maps are of class Dictionary where the key is the command and the value is a class with three members: callback, arguments, description.

This is an upgrade on the idea of using an array as value: [callback, arguments, description]

var coreCommands: Dictionary = {
    "/load/file": [loadCommandFile, "path:s", "Load a file blah blah..."]
    "/set": [setVar, "varName:s value:*", "Set a variable to a value..."]
    ...

Help files on any format can be generated from this.

The _init for CommandDescription would take those three arguments:

func _init(fn: Callable, args: String, desc: String):
    callable = fn
    argsDescription = args
    description = desc

[totalgee]

Actually, if we make a class for these Dictionary entries (as I think we should), it would be more like this:

# Core commands:
var coreCommands: Dictionary = {
    "/load/file": CommandDescription.new(loadCommandFile, "path:s", "Load a file blah blah..."),
    "/set": CommandDescription.new(setVar, "varName:s value:*", "Set a variable to a value..."),
    ...
}

[loopier]

To document /def I suggest using comments in the command files:

# load an ANIMation and create an ACTOR with it.
/def /bla actor:s anim:s
    /load $anim
    /create $actor $anim

Should create a CommandDescriptio.new(executeCommands, "actor:s anim:s", "Load an ANIMation and create an ACTOR with it.").

This might force us to convert /defs into CommandDescription using a callable executeCommands that would evaluate the array of commnads, which might make everything more consistent. Currently it's a dictionary. Also, the argsDescription should be part of the /def command, which I'm not sure we want. I can't think of another way of making it consistent with the rest of the documentation.

Another option is to add a /description command in the /def. Or just ignore all this and list the array of commands as it is (dump the /def code).

[totalgee]

I think when a def is defined, it could use the CommandDescription as you describe, except the callable could be a lamda function that calls executeCommands (or whatever, not looking at the code right now) with the array of commands "bound" to it. Sorry, this doesn't directly answer your question about documentation, but I think what you suggest could be made to work for that.

[loopier]

I diverged from here when moving most of the core OSC commands to /defs. Most of the docs now are comments in the .ocl file. I decided unilaterally to use AsciiDoc syntax because it felt right. It might not be the best solution, as we were trying to keep everything in one place (code and documentation).

One advantage I see using AsciiDoc is that it's readable, a lot like Godots own BBCode -- or even better--, and it has it's own compiler to HTML which can be associated to a CSS, which is not necessarily used, because both GH and GitLab can render .adoc files out of the box. What we do need is a parser from .ocl to .adoc or HTML. I added a very small and simple script, but it's *nix shell-only and not finished; needs more work.

There was another issue talking about this here. Closing that one to keep things tidy.

[loopier]

The use of AsciiDocs is also justified on most of the documentation being now out of GDScript, in OSC /def files.

I added a doc autogenerator from the (asciidoc) comments in the main OSC file in c00281981c201c8edf38d89e370b51b2c868716b. It can be called with a path to generate a new .adoc file in the ./docs/ directory. In the future it could be used to autogenerate help files from the comments in any file the user might load with /commands/load.