Re: PHPDoc comments suggestions

Hi Alan, Thanks for the suggestions. We do have a version of your excellent @privatePrefix implemented as a command-line "--pear on" as suggested by Christian, which does what you describe. Because the assumption of @access private is automatic, every occasion raises a warning, which may be annoying to some users, but is fine for most. I hadn't known there was a format of "object blah" in phpdoc.de's PHPDoc, but I suppose I could add it. When I wrote the code to do that automatic linking I figured the classname would be enough. Would you like to see the "object blah" format supported? Greg Alan Knowles wrote:

why not just have @privatePrefix on|off and default all prefixed var to private - for the 'pre-PHP5' period? or just accept shorttags for some of these?

var $_xxx    //@var string does something
var $_yyy    //@var string does something
var $_zzz     //@var string does something

on 3) - I thout the format was @return object yours | false ...... rather than @return yours | false ...... Great work BTW. Regards Alan Greg Beaver wrote:

Hi Martin, The alternative is /** * @var string * @access private */ var $_priv1; /** * @var string * @access private */ var $_priv2; There are many projects in PEAR that do not have any @access private tags at all. DocBlock templates are simply useful for marking off sections and saving redundancy and possible typos. If you don't like the look, then it simply means taking the extra time to type in every @access modifier. Or wait for PHP 5 :). DocBlock templates can also be used to specify @param tags for groups of functions that have the same parameters (as in phpDocumentor's parser class), or anything at all. The alternative of leaving things undocumented is the choice that the majority of PEAR projects have made. DocBlock templates will be a quick way to fix this without having to take time away from development. I think the question of readability is subjective. I found reading @tags difficult until I got used to it, and now find it indispensable as a standard way of specifying common elements of documentation. If you have a suggestion of a better way to solve this problem, by all means, let us know, maybe it can be squeezed into the next release. Greg Martin Jansen wrote:

On Mon Mar 17, 2003 at 02:3055PM -0500, Greg Beaver wrote:

/**#@+ * @access private */ /** * @var string */ var $_priv1; /** * @var string */ var $_priv2; /**#@-*/

This syntax is pretty hard to remember and makes reading the source directly pretty hard. Don't we have a better alternative?