Should we ammend point 7 in the coding style guidelines to say that comments following the PHPdoc style are encouraged? This would allow automatic generation of documentation.
Yes, indeed. Someone really should fix that 
Definitely agree. Many already are, of course, but the *quality* varies quite a bit. I'd be happy to write/steal a few lines.
In fact I'm doing it now
In fact I'm doing it now
This any use (attached)? Might drop in, as I tried to use the CSS stuff from the developer doc page.
Yes, please do.
My dev team is using a similar technique for ActionScript. I'll have no
trouble enforcing PHPdoc here!
My dev team is using a similar technique for ActionScript. I'll have no
trouble enforcing PHPdoc here!
So, I guess we need to update existing documentation in each function we touch?
mike
mike
Howard and Mike,
I went through and added skeletal phpdoc comments in as many main libs and classes as I had time to with the hope that developers would see the format and choose to expand the comments that have todo tags and add comments to new functions as added. As you add new functions or make edits to a function please add or expand on existing phpdoc comments.
I've added a guidelines document to cvs contrib, your feedback is welcome:
cvs:/contrib/php_doc_guidelines/moodle-phpdoc-guidelines.html
I went through and added skeletal phpdoc comments in as many main libs and classes as I had time to with the hope that developers would see the format and choose to expand the comments that have todo tags and add comments to new functions as added. As you add new functions or make edits to a function please add or expand on existing phpdoc comments.
I've added a guidelines document to cvs contrib, your feedback is welcome:
cvs:/contrib/php_doc_guidelines/moodle-phpdoc-guidelines.html
It's none of my business as I have never contributed code to Moodle, but PHPDoc is a very, very good idea.
I've posted phpdoc output from a full run against the entire Moodle 1.6dev code. Developers, here is an example as to why you should be including good phpdoc comments for every new function, define, class and file and why you should be updating the comments on functions as you use them.
http://moodle.sourceforge.net/dhawes-phpdoc
http://moodle.sourceforge.net/dhawes-phpdoc