Date: Sat, 06 Apr 2002 12:49:23 -0500 From: The Anarcat <anarcat@anarcat.dyndns.org> To: libh@freebsd.org Subject: code documentation systems (listing phase) Message-ID: <3CAF3523.2070801@anarcat.dyndns.org>
next in thread | raw e-mail | index | archive | help
Hi. Since I think the libh project needs to get a fresh kick in the documentation part, I've started to examine the possible systems available in the ports collection and in the links I found on the various sites connected there. I see this as a 3 phase process: [1] listing of possible systems [2] testing [3] choosing the system [4] documenting libh Right now, this mail is (1) the listing phase. I'll get to (2) testing shortly. Then I'll suggest a (3) chosen system. (4) Documenting libh would imply plugging various makefiles rules to allow easy re-creation of libh documentation. I thought of creating a seperate branch for this process so that we can easily turn around if we find out it's a wrong way of doing things. Merging the branches once the documentation system is in place should be easy since it will touch only comments and not code. Commits to comments & doc should be directed to the doc branch and code commits to the main. This documentation could then be published on the website. This might be a problem though, since libh's project page is auto-generated itself using sgml files. Would it be possible to plug libh's documentation build in the webpage's? I hope so. So here are my results. I'll start by providing a listing of the systems and the short description of each (taken pkg-comment, where available). I then note some comments taken from the site's respective propaganda machines and some personal evaluation and critics on the system. Note that I haven't tried any of these. I'll start testing those later on but I want to get the pulse of the list wrt these tools. Most of these tools are available as ports in devel/. 1- ccdoc: Extracting comments from C++ source and generating HTML WWW: http://www.joelinoff.com/ccdoc/ Looks interesting. Simple yet powerful: needs no setup to run. Can grok javadoc-like syntax. Generates HTML. Source distro 200K. 2- cxref: C program cross-referencing & documentation tool WWW: http://www.gedanken.demon.co.uk/cxref/ No C++ support, so we can already forget this one. 3- doc++: Javadoc style C++ documentatation system WWW: http://docpp.sourceforge.net/ Supports cross references, latex and html, automatic callgraph generation as Java applets for HTML (which might be a problem). I don't think we should use this one since it creates the html graphs as applets. I haven't tested the applets so I can't say how powerful they are, but that's because the java plugin doesn't work in my mozilla here. ;) Source distro 300K. 4- doxygen: A documentation system for C and C++ WWW: http://www.stack.nl/~dimitri/doxygen/ Reknown. My system of choice. Generates latex and html but also nroff, linked pdf, compressed html, postscript, and rtf. Can generate doc on undocumented systems. Automatic dependency, inheritences and collaboration graphs generation. Uses Qt for platform abstraction and has a GUI wizard. Can use dot(1) from AT&T's graphics/graphviz for more advanced graphs Source distro 2Mb. 5- understand_c: Understand can parse a C/C++ project helping reverse engineer it *needs a license* documents large projects with hierarchies and various trees, cross-refs. Seems it could be useful in figuring out what went through Eugene's head when he coded libh. :) I don't think this would be useful as a documentation system, but more an exploration system. 6- scandoc: A C/C++ documentation generator http://scandoc.sourceforge.net/ I can't browse the example doc with mozilla. Seems to support javadoc-style commenting. Seem to be poor compared to the others. 7- robodoc: Code reference program similar to cxref that produces HTML Supports a lot of languages (Assembler, C, Perl, LISP, Occam, Tcl/Tk, Pascal, Fortran, shell scripts, and COBOL, basically any language that supports comments/remarks) and outputs (HTML, ASCII, AmigaGuide, LaTeX, or RTF format) Doesn't seem to generate graphs, Its support for a lot of language makes it less powerful at parsing a particular language. It's interesting to see there's support for Tcl, but since most of libh's internals are written in C++, I don't think it would be so useful. 8- synopsis: http://synopsis.sourceforge.net/ scalable, multiple language support, multiple parser support multiple format support. can generate inheritence graphs and trees, but not as cute as doxygen's :) In summary, I'd like to get a clear cut at which is the best, but it's probably not possible. I guess we could use doxygen. It seems really powerful and flexible and could withstand libh's complexity. I'll try the various tools on the libh tree to see how they behave. A. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-libh" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?3CAF3523.2070801>