Updating the File-Level Docblocks

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Updating the File-Level Docblocks

ralphschindler
Hey all,

After a few discussions with various people (some with legal
perspective, some not), we've come to the conclusion that we'd like to
make the file-level docblocks in ZF more succinct.

The new file-level header should look like this:

from: https://gist.github.com/2578422

<?php
/**
  * Zend Framework (http://framework.zend.com/)
  *
  * @link      http://github.com/zendframework/zf2 for the canonical
source repository
  * @copyright Copyright (c) 2005-2012 Zend Technologies USA Inc.
(http://www.zend.com)
  * @license   http://framework.zend.com/license/new-bsd New BSD License
  * @package   Zend_Package
  */


Let me know if you have any questions or comments,
-ralph
Reply | Threaded
Open this post in threaded view
|

Re: Updating the File-Level Docblocks

DeNix
On 03.05.2012 22:11, Ralph Schindler wrote:

> Hey all,
>
> After a few discussions with various people (some with legal
> perspective, some not), we've come to the conclusion that we'd like to
> make the file-level docblocks in ZF more succinct.
>
> The new file-level header should look like this:
>
> from: https://gist.github.com/2578422
>
> <?php
> /**
>  * Zend Framework (http://framework.zend.com/)
>  *
>  * @link      http://github.com/zendframework/zf2 for the canonical
> source repository
>  * @copyright Copyright (c) 2005-2012 Zend Technologies USA Inc.
> (http://www.zend.com)
>  * @license   http://framework.zend.com/license/new-bsd New BSD License
>  * @package   Zend_Package
>  */
>
>
> Let me know if you have any questions or comments,
> -ralph

Hi Ralph,
does this change affect class-level docblock? If so how class-level
block should look like?

Thanks
Denis

Reply | Threaded
Open this post in threaded view
|

Re: Updating the File-Level Docblocks

weierophinney
Administrator
-- Denis Portnov <[hidden email]> wrote
(on Thursday, 03 May 2012, 10:20 PM +0400):

> On 03.05.2012 22:11, Ralph Schindler wrote:
> > Hey all,
> >
> > After a few discussions with various people (some with legal
> > perspective, some not), we've come to the conclusion that we'd
> > like to make the file-level docblocks in ZF more succinct.
> >
> > The new file-level header should look like this:
> >
> > from: https://gist.github.com/2578422
> >
> > <?php
> > /**
> >  * Zend Framework (http://framework.zend.com/)
> >  *
> >  * @link      http://github.com/zendframework/zf2 for the  canonical source repository
> >  * @copyright Copyright (c) 2005-2012 Zend Technologies USA Inc.  (http://www.zend.com)
> >  * @license   http://framework.zend.com/license/new-bsd New BSD License
> >  * @package   Zend_Package
> >  */

<snip>

IIRC, we should have the @category annotation in the file-level, and not
the @package annotation.

<snip>
> does this change affect class-level docblock? If so how class-level
> block should look like?

The only change (and it's likely already like this) is that the
@package, and @subpackage annotations will be in the class-level block
(and not the file-level), and the @category annotation does not need to
be in the class-level (see above).

--
Matthew Weier O'Phinney
Project Lead            | [hidden email]
Zend Framework          | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc
Reply | Threaded
Open this post in threaded view
|

Re: Updating the File-Level Docblocks

xoops
Don't know if you are aware of this. Just in case:

The @category tag is used to organize groups of packages together but is deprecated in favour of occupying the top-level with the @package tag. As such usage of this tag is NOT RECOMMENDED.



On Fri, May 4, 2012 at 2:51 AM, Matthew Weier O'Phinney <[hidden email]> wrote:
-- Denis Portnov <[hidden email]> wrote
(on Thursday, 03 May 2012, 10:20 PM +0400):
> On 03.05.2012 22:11, Ralph Schindler wrote:
> > Hey all,
> >
> > After a few discussions with various people (some with legal
> > perspective, some not), we've come to the conclusion that we'd
> > like to make the file-level docblocks in ZF more succinct.
> >
> > The new file-level header should look like this:
> >
> > from: https://gist.github.com/2578422
> >
> > <?php
> > /**
> >  * Zend Framework (http://framework.zend.com/)
> >  *
> >  * @link      http://github.com/zendframework/zf2 for the  canonical source repository
> >  * @copyright Copyright (c) 2005-2012 Zend Technologies USA Inc.  (http://www.zend.com)
> >  * @license   http://framework.zend.com/license/new-bsd New BSD License
> >  * @package   Zend_Package
> >  */

<snip>

IIRC, we should have the @category annotation in the file-level, and not
the @package annotation.

<snip>
> does this change affect class-level docblock? If so how class-level
> block should look like?

The only change (and it's likely already like this) is that the
@package, and @subpackage annotations will be in the class-level block
(and not the file-level), and the @category annotation does not need to
be in the class-level (see above).

--
Matthew Weier O'Phinney
Project Lead            | [hidden email]
Zend Framework          | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc



--

Taiwen Jiang (aka D.J.)

Build Xoops Engine
web and mobile application platform

CTO for EEFOCUS.com
Leading social platform for electronics professionals


Reply | Threaded
Open this post in threaded view
|

Re: Updating the File-Level Docblocks

akrabat
In reply to this post by ralphschindler
Can we add in a summary line about what the point of the file is?

It would be really useful to have a one or two liner at the the top that explains why the file exists at all.


Regards,

Rob...


On 3 May 2012, at 19:11, Ralph Schindler wrote:

> Hey all,
>
> After a few discussions with various people (some with legal perspective, some not), we've come to the conclusion that we'd like to make the file-level docblocks in ZF more succinct.
>
> The new file-level header should look like this:
>
> from: https://gist.github.com/2578422
>
> <?php
> /**
> * Zend Framework (http://framework.zend.com/)
> *
> * @link      http://github.com/zendframework/zf2 for the canonical source repository
> * @copyright Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
> * @license   http://framework.zend.com/license/new-bsd New BSD License
> * @package   Zend_Package
> */
>
>
> Let me know if you have any questions or comments,
> -ralph

Reply | Threaded
Open this post in threaded view
|

Re: Updating the File-Level Docblocks

weierophinney
Administrator
In reply to this post by xoops
-- D. J. <[hidden email]> wrote
(on Friday, 04 May 2012, 09:15 AM +0800):
> Don't know if you are aware of this. Just in case:
> http://www.phpdoc.org/docs/latest/for-users/tags/category.html
>
>
>     The @category tag is used to organize groups of packages together but is
>     deprecated in favour of occupying the top-level with the @package tag. As
>     such usage of this tag is NOT RECOMMENDED.

Yeah -- Ralph noticed that yesterday, and also has an email in to the
phpdoc team to find out if the @package annotation needs to be in the
file-level at all.


> On Fri, May 4, 2012 at 2:51 AM, Matthew Weier O'Phinney <[hidden email]>
> wrote:
>
>     -- Denis Portnov <[hidden email]> wrote
>     (on Thursday, 03 May 2012, 10:20 PM +0400):
>     > On 03.05.2012 22:11, Ralph Schindler wrote:
>     > > Hey all,
>     > >
>     > > After a few discussions with various people (some with legal
>     > > perspective, some not), we've come to the conclusion that we'd
>     > > like to make the file-level docblocks in ZF more succinct.
>     > >
>     > > The new file-level header should look like this:
>     > >
>     > > from: https://gist.github.com/2578422
>     > >
>     > > <?php
>     > > /**
>     > >  * Zend Framework (http://framework.zend.com/)
>     > >  *
>     > >  * @link      http://github.com/zendframework/zf2 for the  canonical
>     source repository
>     > >  * @copyright Copyright (c) 2005-2012 Zend Technologies USA Inc.  (
>     http://www.zend.com)
>     > >  * @license   http://framework.zend.com/license/new-bsd New BSD License
>     > >  * @package   Zend_Package
>     > >  */
>
>     <snip>
>
>     IIRC, we should have the @category annotation in the file-level, and not
>     the @package annotation.
>
>     <snip>
>     > does this change affect class-level docblock? If so how class-level
>     > block should look like?
>
>     The only change (and it's likely already like this) is that the
>     @package, and @subpackage annotations will be in the class-level block
>     (and not the file-level), and the @category annotation does not need to
>     be in the class-level (see above).

--
Matthew Weier O'Phinney
Project Lead            | [hidden email]
Zend Framework          | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc
Reply | Threaded
Open this post in threaded view
|

Re: Updating the File-Level Docblocks

Maks3w
This post has NOT been accepted by the mailing list yet.
One question. What is the porpuse of @package and @subpackage?

The namespace statement give a clear vision about the component and subcomponent. Even if we consult the API doc is better look for namespace rather than packages.