Saturday 19 November, vers 0h, Tobias Toedter écrivit : > > 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.
You mean like http://download.gna.org/savane/docs/developer-reference.php-frontend/ (outdated) On the overall, we may include in the trunk, in doc/devel, the conffile needed to put up such documentation (that should be put in the download area), but putting generated files into the trunk would not be clean and useful. > 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); > } As I said in comment of another item, many functions should have better name, name that says what we want do it with, not what is actually technically do. The later case should happen only when a function is only meant to do a technical thing but not meant for general usage all over the code. But I'm not very fond of the idea of this happening on the COOKBOOKandEXPORT branch. I would not have time to resolve merge conflict or to debug things others than the one being implemented. Well, doing it on the trunk would not be wise either.. Well, if you want to start doing that, and so on the current branch, please post task related to that and post a comment when you start working on an area mentioning which one (like /my or whatever). And please, ask me before touching include/trackers and include/trackers_run so we can avoid merge conflict. -- Mathieu Roy +---------------------------------------------------------------------+ | General Homepage: http://yeupou.coleumes.org/ | | Computing Homepage: http://alberich.coleumes.org/ | | Not a native english speaker: | | http://stock.coleumes.org/doc.php?i=/misc-files/flawed-english | +---------------------------------------------------------------------+ _______________________________________________ Savane-dev mailing list [email protected] https://mail.gna.org/listinfo/savane-dev
