[geeklog-devel] Source code documentation

[Dirk Haun]

As you probably know, the Geeklog source code is run through phpDocumentor (again now - it was broken and therefore outdated for quite some time) every night. The result is published here:

http://project.geeklog.net/src/

This uses an old version of phpDocumentor which isn't supported any more. I'd like to move this process to Jenkins, so we can more easily see what's going on an get notifications if it breaks.

Which made me wonder if we should stick with that old phpDocumentor version or use something else. Here's a quick summary of the options:

There's a phpDocumentor version 2, which is really just what used to be called DocBlox now using the phpDocumentor name. In other words, it's an entirely different tool now. It's very configurable but I couldn't get it to work properly on our somewhat limited setup.

phpDox looks nice and is easy to install. But it's really made for code that's entirely OO. In Geeklog, we have a lot of non-OO code which simply won't show up in output generated by phpDox.

ApiGen could be an option. It's still somewhat OO-centric but at least lists all the non-OO functions. Here's the output for Geeklog's source code right now:

http://project.geeklog.net/src2/  (temp. location - may go away at any time)

The remaining alternative I haven't tried is doxygen. I've used this tool before, but for C source code. It does have some support for PHP but, unlike the others, is not really made with PHP in mind.


To summarize: I think our options (unless I missed some other alternatives) are to either stick with phpDocumentor 1.4.3 or switch to ApiGen.

Any preferences or comments?

bye, Dirk


-- 
http://www.themobilepresenter.com/