added a comment - - edited
$tagtype types, I agree using @see would be good however there is nothing to "see" as these types are not defined in the code. I have tried to update the code so it's less hostile to updates. I've also added a comment about this to the Tag API overhaul ticket MDL-31090
As for "@access private", this is different from private methods: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.access.pkg.html
There was a conversation at the time about the use of @access private on functions such as these, however unfortunately it was not documented in the coding style.
coursetabslib.php : coursetag_rss_feeds() & coursetag_get_official_keywords() are commented but their doc blocks have been modified into block comments. this seems ok, but maybe we should discuss and share that this is how we should do it if and when commenting. I would say that commented functions should really be removed. (this may be a separate issue/subtask)
I agree about the commented out code being deleted. I've created an MDL for it
personally i prefer the argument related phpdocs (@params/@return) to be spaced away from other (@package) phpdoc tags for easier source code reading. i don't think there is any rule though.
I don't mind either way, however it's not in the standard and if we want to make it part of the standard then it should be required of all the doc issues and not just this one. I think it's far more important to get these changes through so that developers can start using the improved documentation.
I've made changes to everything else you mentioned. Thanks.