Hi all, one thing I was always missing in Savane's codebase was proper and easy to understand documentation. Quite a few functions are documented really well, others have no single line of explanation near them.
The PHP code is huge (roughly 40.000 lines in 200 files), and I wish there were simple means to get an overview. It's especially hard for new developers to get an overview. So I propose not only to document each and every function, but to do it in a clever way. Clever means that some program should be able to generate documentation from the source code comments. During my search for such a system, I discovered phpDocumentor (<http://www.phpdoc.org/>). It uses a simple markup syntax for function documentation and will generate some nice looking API docs. I did some markup for the new function utils_unixtime_to_date() and the (now deprecated) function format_date(). You can see the results for the file utils.php here: <http://www.bupp.de/savane-doc/> Note that phpDocumentor does not need to be shipped with Savane, the resulting pages are HTML only. Furthermore, the program can generate PDF files, should we need that. And while we're happily documenting, there's another aspect we get for free: We could get rid of all those deprecated functions, which are nothing more than something like this: # DEPRECATED function old_func($param) { new_func($param); } Cheers, -- Tobias "Only two things are infinite, the universe and human stupidity, and I'm not sure about the former" -- Albert Einstein
pgpAZ2jmsyAY1.pgp
Description: PGP signature
_______________________________________________ Savane-dev mailing list [email protected] https://mail.gna.org/listinfo/savane-dev
