Make using `DeclareGlobalName` for functions work

[ssiccha]

When I use DeclareGlobalName together with an @Description comment, then I get this, and I can't use the @Arguments comment:

#! @Description
#!   Insert documentation for your function here
#! @Arguments foo, bar
DeclareGlobalName( "ClassicalMaximals_Example2" );

Edit: I think adding an @Arguments comment should make AutoDoc handle the variable in question as a function instead of as a global variable.

[fingolfin]

Unfortunately DeclareGlobalName does not tell us whether the referenced object is a function or a variable; it can be used for either. This is fundamentally impossible.

I guess we could/should add a way to indicate the type...

In the meantime you could just use DeclareGlobalVariable/Function

[ssiccha]

I guess we could/should add a way to indicate the type...

Could we add logic into AutoDoc that if a global variable gets an @Arguments comment, then it should be handled as a function?

And in the meantime I'll use DeclareGlobalFunction, yes.

[fingolfin]

In theory: sure, I'd be happy to merge such a change.

In practice, someone has to figure out how to do it ;-)

[ssiccha]

Is this something we could let one of the student assistants do? Not now but in a few months, say. I have no idea how AutoDoc works internally, so I really don't know.

[fingolfin]

That depends on them; also on how much GAP they'll pick up. But diving into a new unfamiliar codebase is always challenging.

Anyway, I could so it in principle, but my time is limited (time I was able to fully dedicate to work today so far: 0. At least I could type some issue replies or emails on my phone...

[fingolfin]

Relevant place in the code:

AutoDoc/gap/Parser.gi

Line 111 in f47e3fd

elif PositionSublist( type, "DeclareGlobalName" ) <> fail then

-- around here the various "Declare" commands are handled. Looking at that I would hope one could hack the handler for @Arguments to "convert" the node types as needed

[fingolfin]

Let me also point out that in general, it would be good if one could attach a AutoDoc comment to a function declared via BindGlobal, at least in the "obvious" cases, i.e. BindGlobal("FOO", function(...) where we see a literal function keyword (for BindGlobal("FOO", BAR); we have no information about what BAR is).

Because in many cases I think it is by far preferable to directly attach a doc comment to the implementation, not some otherwise useless "declaration".