On Friday 14 September 2007 00:55, Julien Kerihuel wrote: > The more we develop on OC and introduce new functions (or modify > existing ones), the more updating hand written man pages become painful > and cause errors/inconsistencies in the documentation. > > We initially suggested to use doxygen as a potential replacement. Brad > Hards is ready to help in making this step forward. (It's always nice to > meet doxygen fan (-;).
I've had a go at this, and it is looking OK. Essentially what I've done so far: 0. Added the doxygen config file (Doxyfile) 1. Taken the content from doc/man/man3 and moved it into the matching places in libmapi/*.c. I fixed a few typos, and some errors that I noted. 2. Modified scripts/mkproto.pl so that the comments are also put into the header. This is the most hairy part, because I don't grok perl at all. I used the samba4 script as a model - thanks to Jelmer for the suggestion. 3. Added the examples from the linuxconf.eu paper. 4. Added some content for the "main page" (start page). Mostly from the intro to the linuxconf.eu paper. 5. Added an example of additional content. This page (on MAPI concepts) is only to show what is possible. Again, content is from the linuxconf.eu paper. I'd like to extract more from that paper, including the diagrams. You can see the results here: http://www.frogmouth.net/oc-apidocs/html/index.html There is also a PDF manual: http://www.frogmouth.net/oc-apidocs/latex/refman.pdf (not very useful IMO, html is much better). The patch (298K) is at http://www.frogmouth.net/doxygen-ify-2007-09-27.patch It is too big for the list, even gzip'ed. There are still some parts that aren't as good as I'd like: - the man3 version is pig-ugly - the documentation shows <libmapi/proto.h>, and there should be some explanation that the right header is <libmapi.h>. That might be quite hard to fix. - there are too many undocumented functions/data structures/enums. I need to suppress some of it, and fix the rest. I'm undecided whether this should be applied - I think it would be good to do so, just not too happy with the deficiencies.
pgp7NXR0ZU0mo.pgp
Description: PGP signature
_______________________________________________ devel mailing list [email protected] http://mailman.openchange.org/listinfo/devel
