[GAP Forum] Equivalent of Doxygen for GAP

[Ivan Andrus]

Oh, okay.  Well I guess that settles that.  Do you still have the awk script easily accessible, or should I whip something up in perl (that's what else :-) for my own use?  

Or perhaps I'll go with the GAPDoc approach for my own files.  Hmm.  Now I have to decide what sort of support I should add to gap-mode.el.

-Ivan

On May 28, 2011, at 8:55 PM, Martin Schoenert wrote:

> 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