Comments in PHPdoc style

Comments in PHPdoc style

由Gustav W Delius發表於
Number of replies: 9
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.
評比平均分數： -
In reply to Gustav W Delius

Re: Comments in PHPdoc style

由Howard Miller發表於
Core developers的相片 Documentation writers的相片 Particularly helpful Moodlers的相片 Peer reviewers的相片 Plugin developers的相片
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 reply to Gustav W Delius

Re: Comments in PHPdoc style

由Dirk Herr-Hoyman發表於
Yes, please do.

My dev team is using a similar technique for ActionScript. I'll have no
trouble enforcing PHPdoc here!
評比平均分數： -
In reply to Gustav W Delius

Re: Comments in PHPdoc style

由Mike Churchward發表於
Core developers的相片 Plugin developers的相片 Testers的相片
So, I guess we need to update existing documentation in each function we touch?

mike
評比平均分數： -
In reply to Mike Churchward

Re: Comments in PHPdoc style

由Daryl Hawes發表於
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
評比平均分數： -
In reply to Daryl Hawes

Re: Comments in PHPdoc style

由Marcus Green發表於
Core developers的相片 Particularly helpful Moodlers的相片 Plugin developers的相片 Testers的相片
It's none of my business as I have never contributed code to Moodle, but PHPDoc is a very, very good idea.
評比平均分數： -
In reply to Daryl Hawes

Re: Comments in PHPdoc style

由Daryl Hawes發表於
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
評比平均分數： -