Home > Archive > PHP PEAR Questions and Answers > December 2007 > Re: [PEAR-QA] Re: Need feedback about PEAR Coding Standard relatedto
You are viewing an archived Text-only version of the thread.
To view this thread in it's original format and/or if you want to reply to
this thread please [click here]
| Author |
Re: [PEAR-QA] Re: Need feedback about PEAR Coding Standard relatedto
|
|
| Laurent Laville 2007-12-18, 7:02 pm |
| Gregory Beaver a écrit :
> Chuck Burgess wrote:
>
> @ignore's only intended purpose is to prevent a warning on documenting
> duplicate elements i.e.:
>
> if (blah) {
> class A {}
> } else {
> /** @ignore */
> class A {}
> }
>
> Greg
Well in such example, and if we follow phpcs, we should code twice the
same phpdoc class comment.
if (blah) {
/**
* @param int $p1
* @param int $p2
*/
class A ($p1, $p2) {}
} else {
/**
* @param int $p1
* @param int $p2
* @ignore
*/
class A ($p1, $p2) {}
}
This is why I've ask the possibility not to avoid a properly documented
code (it's not my point of view), but to avoid such situation.
Dupplicate class comment seems useless here !
Laurent
| |
| Laurent Laville 2007-12-19, 7:03 pm |
| Chuck Burgess a écrit :
> On Dec 18, 2007 5:35 PM, Laurent Laville <pear@laurent-laville.org> wrote:
>
>
> I've never seen a class declaration like that... I didn't think PHP would
> allow it. The way I've seen such a situation like this handled before was
> to use an IF conditional around an INCLUDE statement, where TRUE would
> include file A and FALSE would instead include file B.
>
> If I had to document that piece of code above, I'd probably attempt to use a
> docblock template before the IF, containing nearly all the class info, and
> only put minimal *different* info in the two class-adjacent docblocks, and
> be satisfied until such time as we can help get docblock template support
> into phpcs.
Sorry , I was a bit to hurry yesterday night.
Parameters was of course for constructor of class declaration :
if (blah) {
/**
* Class A comment
*
* @category xxx
* @package xxx_yyyy
* @author name <email>
* @license url
* @link url
*/
class A {
/**
* @param int $p1
* @param int $p2
*/
function __construct($p1, $p2) {}
}
} else {
/**
* @ignore
*/
class A {
/**
* @param int $p1
* @param int $p2
*/
function __construct($p1, $p2) {}
}
}
With this code, phpcs, will ask AGAIN the same phpdoc tags (@category,
@package, ...) for class A , and class A ignored .
This is something like that, why I think its too much.
|
|
|
|
|