Ian Eure [2005-01-13 22:40 UTC] The page-level docblock seems redundant for files which only contain a single class.
Perhaps they should only be required for files which contain zero (e.g. a script) or more than one class.
Alan Knowles [2005-01-15 01:32 UTC] you need a transition policy
- Single file Old packages should be updated before next release?????
- Larger Old packages, should at least update main class, - other ones optional, upto maintaner
- New packages should use new standard...
I dont want to put too much burden on already overloaded developers like me ;)
Daniel Convissor [2005-01-17 07:36 UTC] > The page-level docblock seems redundant
> for files which only contain a single
> class.
phpDocumentor produces separate pages for each file and for each class. Thus, both docblocks are needed to produce complete documentation.
Andrew Nagy [2005-01-27 22:25 UTC] The class @version tag could use the $Revision$ cvs tag to show the current CVS version number.
The page @version tag could use the $Name$ cvs tag instead of the $id$ tag since it shows the current file version and not the package version.
The $Id$ tag could be moved to a different location, but is it necessary for PHPDocumentor since we now have the author tag, etc.
Although, I tried using $Name$ in my package and it does not use the tagged version name that I thought the 'pear cvstag' command would create, if it worked right, it might be nice to use.
FYI, Here are others:
http://cvsbook.red-bean.com/cvsbook.html#List%20Of%20Keywords
Louis Mullie [2005-01-27 23:37 UTC] The page-level block states "PHP versions 4 and 5", which should be "PHP version 3" (last license version)
Regards,
Louis Mullie
Ian Eure [2005-01-27 23:47 UTC] >> The page-level docblock seems redundant
>> for files which only contain a single
>> class.
> phpDocumentor produces separate > pages for each file and for each > class. Thus, both docblocks are needed > to produce complete documentation.
Right, but what is that page-level block going to contain? 'This is the file that contains the FooBar_Baz class, part of the FooBar package.'?
The actual info there is what seems unnecessary and redundant, regardless of how phpDocumentor handles it.
Ian Eure [2005-01-27 23:51 UTC] "The class @version tag could use the $Revision$ cvs tag to show the current CVS version number."
I think it makes more sense as-is, with the class taking the package version, and the file taking the CVS revision.
"Although, I tried using $Name$ in my package and it does not use the tagged version name that I thought the 'pear cvstag' command would create, if it worked right, it might be nice to use."
According to the docs, that only works for sticky tags (e.g. branches, created with `cvs tag -b') - PEAR uses regular, non-sticky tags (created with `cvs tag'). Using a package.xml substitution for the package version is clearer anyways, in my opinion.
Daniel Convissor [2005-01-28 15:05 UTC] > The page-level block states
> "PHP versions 4 and 5", which should be
> "PHP version 3" (last license version)
That line talks about which versions of PHP the file can be used with. The license version is covered in the @license tag and the LICENSE block.
Daniel Convissor [2005-01-28 15:13 UTC] > The actual info [in the page-level docblock]
> seems unnecessary and redundant, regardless
> of how phpDocumentor handles it.
Yes, they're kind of redundant, but they're necessary.
Daniel Convissor [2005-01-28 15:19 UTC] > The class @version tag could use the
> $Revision$ cvs tag
...
> The $Id$ tag could be moved to a
> different location,
These issues are already discussed in the RFC.
> The page @version tag could use the
> $Name$ cvs tag instead of the $id$ tag
The CVS manual says it best: "The keyword is expanded only if one checks out with an explicit tag name." That's not how the packaging process works, so $Name$ won't do the trick.
|
