[PEPr] Comment on RFC::Amendment of Docblock Comment Standards

Greg Sherwood (http://pear.php.net/user/squiz) has commented on the proposal for RFC::Amendment of Docblock Comment Standards. Comment: I think having the param name in @param is important. While it may be your intention to ensure they are always in the correct order, I've been caught by phpcs a few times where I have changed the order of params after writing the docs and forget to reorder the tags. Having the param name makes it clear what param the documentation was written for, which makes it far easier for the next developer who comes along to read the code docs or generated docs. Automated tools are never going to know which param you were talking about, so it is likely that some docs will be generated with documentation assigned to the wrong param, which is IMO just as bad as having no docs at all. Proposal information: http://pear.php.net/pepr/pepr-proposal-show.php?id=580 -- Sent by PEPr, the automatic proposal system at http://pear.php.net