Redundancy in class docblocks/comments?

[euromark]

Looking at some core files I noticed redundancy and possible conflicts resulting from this for some class comments:

/**

* Behavior for binding management.

*

* Behavior to simplify manipulating a model's bindings when doing a find operation

*

* PHP 5

*

* ...

*/

/**

* Behavior to allow for dynamic and atomic manipulation of a Model's associations 

* used for a find call. Most useful for limiting the amount of associations and 

* data returned.

*

* ...

*/

In this case the description above seems to be the short version of below. but in other files like Tree behavior there are the same sentences. Only of the two is updated, though.

Is there a reason why there are two doc blocks where there could be one - or at least only one description? If you fix a mistake or update one of them you might easily miss to update the other one (A good example is the redundancy in RequestHandler - quite a long text passage):

/**

* Request object for handling alternative HTTP requests

*

* Alternative HTTP requests can come from wireless units like mobile phones, palmtop computers,

* and the like.  These units have no use for Ajax requests, and this Component can tell how Cake

* should respond to the different needs of a handheld computer and a desktop machine.

*

* ...

*/

App::uses('Xml', 'Utility');

/**

* Request object for handling alternative HTTP requests

*

* Alternative HTTP requests can come from wireless units like mobile phones, palmtop computers,

* and the like. These units have no use for Ajax requests, and this Component can tell how Cake

* should respond to the different needs of a handheld computer and a desktop machine.

*

* ...

*/

At least that's what has been happening so far. I am not worried about the filesize so much, of course^^ I still think it would make sense to only display the description once - in the second doc block.

I was wondering what the coding guidelines for this are.

[Juan Basso]

The first docblock represents the file, and the second the class. We have one class per file, so it makes hard to put something different.
The file comment is a kind of standard in many languages to include copyright, package, and other information.

Juan Basso

[mark_story]

I'd like to remove the description text from the file comments and leave those for copyright/version information only.  The actual documentation should be with the class doc as that's what the API generation tool reads and uses.

As to why there are duplicates, there isn't a good answer other than they exist.  I don't think its useful to create duplication personally, but I haven't had time to go through all the files and remove the redundancy.

-Mark

[euromark]

I agree with you, Mark

they should belong to the class itself

the file doc only needs the copyright/version information

knowing this I can also help to correct the files over time

thx