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