[GAP Forum] Equivalent of Doxygen for GAP

[Martin Schoenert]

Hello everybody,

It was just a convention.  I know that for certain,
because I was the one who started it.

Initially I used it in the C source files.  So there
was no idea to generate documentation from
those comments (because there never was
documentation of the kernel apart from the
comments).  The whole purpose was really
to be able to extract the meta information
(name and version of a module, functions and
variables contained, etc.) with a simple grep
command.

Later I also used it for the GAP library files.
I did write an AWK script (what else ;-) to
extract those comments for the documentation.
But we realized that we made so many
changes to the documentation (e.g. adding
tutorial chapters for which there was no
corresponding source file, adding longish
examples which would have made the source
files harder to read, etc.) that it seemed easier
to separate source and documentation.

YMMV of course.

Initially only few letters where used.
I think I recall
F for functions,
V for variables,
A for file meta information,
H for history,
Y for copyright.
Over the years many more letters were
added of course.

regards, martin

Am 28.05.2011 um 17:42 schrieb Ivan Andrus <darthandrus at gmail.com>:

> 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
> 
> 
> _______________________________________________
> Forum mailing list
> Forum at mail.gap-system.org
> http://mail.gap-system.org/mailman/listinfo/forum