FAQ
As suggested by Greg Sherwood, and because I would like to know opinion
of community, about a request I've post on PHP_CodeSniffer.

Details of this request is available at [1] with answer of Greg.

What are your point of view : QA / PEAR teams group first ?

Laurent

[1] http://pear.php.net/bugs/bug.php?id=12700

Search Discussions

  • Philippe Jausions at Dec 17, 2007 at 3:05 pm
    Hi Laurent,

    I'd agree with Greg that @ignore should only be used to not have
    documentation included for the **end user**.

    I believe it is best to have **all** code in PEAR to be properly
    documented with inline phpDoc, and not use @ignore as an excuse for
    sloppy coding practice.

    -Philippe


    Laurent Laville wrote:
    As suggested by Greg Sherwood, and because I would like to know opinion
    of community, about a request I've post on PHP_CodeSniffer.

    Details of this request is available at [1] with answer of Greg.

    What are your point of view : QA / PEAR teams group first ?

    Laurent

    [1] http://pear.php.net/bugs/bug.php?id=12700
  • Chuck Burgess at Dec 17, 2007 at 4:31 pm

    On Dec 17, 2007 9:04 AM, Philippe Jausions wrote:

    Hi Laurent,

    I'd agree with Greg that @ignore should only be used to not have
    documentation included for the **end user**.

    I believe it is best to have **all** code in PEAR to be properly
    documented with inline phpDoc, and not use @ignore as an excuse for sloppy
    coding practice.

    -Philippe
    I agree with Greg and Philippe... I had been holding off on replying
    already, since you'd asked for QA and PEAR Group opinions first :)
    --
    CRB

    Let me introduce you to my very own DMCA-protected encryption key:
    BC 1B 64 4A 8D DE 49 E8 C3 7D CC EE 1A AD EE F5
    (compliments of Freedom-to-Tinker http://www.freedom-to-tinker.com/?p=1155)
  • Gregory Beaver at Dec 17, 2007 at 10:39 pm

    Chuck Burgess wrote:
    On Dec 17, 2007 9:04 AM, Philippe Jausions wrote:

    Hi Laurent,

    I'd agree with Greg that @ignore should only be used to not have
    documentation included for the **end user**.

    I believe it is best to have **all** code in PEAR to be properly
    documented with inline phpDoc, and not use @ignore as an excuse for sloppy
    coding practice.

    -Philippe
    I agree with Greg and Philippe... I had been holding off on replying
    already, since you'd asked for QA and PEAR Group opinions first :)
    @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
  • Laurent Laville at Dec 18, 2007 at 11:35 pm

    Gregory Beaver a écrit :
    Chuck Burgess wrote:
    On Dec 17, 2007 9:04 AM, Philippe Jausions <Philippe.Jausions@11abacus.com>
    wrote:
    Hi Laurent,

    I'd agree with Greg that @ignore should only be used to not have
    documentation included for the **end user**.

    I believe it is best to have **all** code in PEAR to be properly
    documented with inline phpDoc, and not use @ignore as an excuse for sloppy
    coding practice.

    -Philippe
    I agree with Greg and Philippe... I had been holding off on replying
    already, since you'd asked for QA and PEAR Group opinions first :)
    @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
  • Chuck Burgess at Dec 19, 2007 at 12:29 am

    On Dec 18, 2007 5:35 PM, Laurent Laville wrote:
    if (blah) {
    /**
    * @param int $p1
    * @param int $p2
    */
    class A ($p1, $p2) {}
    } else {
    /**
    * @param int $p1
    * @param int $p2
    * @ignore
    */
    class A ($p1, $p2) {}
    }
    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.
    --
    CRB

    Let me introduce you to my very own DMCA-protected encryption key:
    BC 1B 64 4A 8D DE 49 E8 C3 7D CC EE 1A AD EE F5
    (compliments of Freedom-to-Tinker http://www.freedom-to-tinker.com/?p=1155)
  • Laurent Laville at Dec 19, 2007 at 6:32 pm

    Chuck Burgess a écrit :
    On Dec 18, 2007 5:35 PM, Laurent Laville wrote:

    if (blah) {
    /**
    * @param int $p1
    * @param int $p2
    */
    class A ($p1, $p2) {}
    } else {
    /**
    * @param int $p1
    * @param int $p2
    * @ignore
    */
    class A ($p1, $p2) {}
    }
    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.
  • Chuck Burgess at Dec 19, 2007 at 7:15 pm

    On Dec 19, 2007 12:32 PM, Laurent Laville wrote:

    Sorry , I was a bit to hurry yesterday night.

    Parameters was of course for constructor of class declaration :
    I wasn't meaning that the format of the code would have been incorrect
    specifically because of those parameters, though now that you mention it I
    guess technically you're right about that. I was meaning that I thought
    putting an entire class declaration block inside an IF block was not legal.
    So,

    if ($flag) {
    class A {}
    } else {
    class A {}
    }

    is enough to display what I thought wasn't legal. Assuming this *is *legal,
    then that concern of mine is put to rest.

    Getting back to the original question, I wonder, then, would a future
    possibility of phpcs handling docblock templates be enough to allow doing
    this for now:

    /**#@+
    * our declaration of Class A
    * @package MyPackage
    */
    if ($flag) {
    /**
    * @internal class as set by a TRUE $flag
    */
    class A {}
    } else {
    /**
    * @internal class as set by a FALSE $flag
    * @ignore
    */
    class A {}
    }
    /**#@-*/

    That helps mitigate the duplication of putting two fully populated docblocks
    with each class declaration block. Though again, this means that it will
    remain a CS warning/error until such time as we get docblock template
    handling into PHPCS.

    Now, the @ignore means that the second class structure definition won't be
    documented by PhpDocumentor, so no one reading your API doc will know
    anything about it, particularly what makes it any different from the first
    class structure definition that *is* visible in the API doc. But of course
    that is an API doc concern and not a PHPCS concern.
    --
    CRB

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
grouppear-qa @
categoriesphp
postedDec 16, '07 at 2:29p
activeDec 19, '07 at 7:15p
posts8
users4
websitepear.php.net

People

Translate

site design / logo © 2022 Grokbase