[GAP Forum] Equivalent of Doxygen for GAP

[Ivan Andrus]

On May 28, 2011, at 7:52 AM, Keshav Rao Kini wrote:

> Hi Ivan,
> 
> Regarding the "C", I notice that there is a line in Frank Lübeck's vim
> syntax file for GAP code which reads "syn match gapFunLine
> '^#[FVOMPCAW] .*$' contained", so I guess FVOMPCAW are the possible
> values of that letter. What they mean, I don't know... Similar
> patterns also appear in the GAP source code (i.e. the C code in the
> src/ directory), so it looks to me like it might just be a style
> convention of the GAP authors.

I have seen those as well.  A quick grep through .g .gi and .gd files finds the following letters are all used:
ABDEFHIMNOPRTVWXY

The purpose of some of them is fairly easy to guess, for example Y must be for copyright information.

I find it hard to believe that it's merely a style convention (though of course it's possible) with no automated way to get information back out of it.  So if there isn't a way to create documentation from it, I may have to write one. :-)  I am a huge fan of having documentation as close to the code as possible.

> There is something kind of like docstrings mentioned in Chapter 4 of
> the GAPDoc-1.3 manual, but it's not automatically generated, and it
> has an XML-ish syntax rather than being plaintext like Doxygen or
> similar systems. I'm not sure if there's something else I haven't
> discovered.

Moreover, the examples I have looked at in code do not seem to use the xml syntax of GAPDoc.

-Ivan

> -Keshav
> 
> Disclaimer: the boilerplate text at the foot of this email has been
> added automatically by my mail server. This was not done by my request
> (rather the opposite) so please disregard it.
> 
> 
> 2011/5/28 Ivan Andrus <darthandrus at gmail.com>:
>> I have some gap files with functions that I have written.  They are not part of any package, nor I suspect will they ever be.  I would like to add some doxygen-style documentation and have it picked up by the GAP help system.  I have seen several gap files with documentation that looks something like:
>> 
>> ####################################################
>> ##
>> #C  SomeFunction( arg1, ) . . .  . . . . . . . Short description
>> ##
>> ##  Some long documentation describing what it's meant to do,
>> ##  limits, caveats, or whatever
>> 
>> I have looked at the GAPDoc package which I thought might be involved but it seems to be completely different.  I have been completely unable to find documentation for either the format (e.g. what does the C mean), or how to get it into GAP's help system.
>> 
>> What is the best/easiest way to deal with such doxygen-style documentation?
>> 
>> -Ivan
>> _______________________________________________
>> Forum mailing list
>> Forum at mail.gap-system.org
>> http://mail.gap-system.org/mailman/listinfo/forum