2

I can't find anything saying in PSR about where should placed comment about class and namespace. Is it should be first description of class or namespace?

<?php
/**
 * Some description about this class
 *
 * @author      Mr. Anderson
 * @since       06/09/17
 * @package
 *
 */

namespace MyNamespace;

class MyClass
{
}

Or properly that?

<?php

namespace MyNamespace;

/**
 * Some description about this class
 *
 * @author      Mr. Anderson
 * @since       06/09/17
 * @package
 *
 */

class MyClass
{
}
u_mulder
  • 54,101
  • 5
  • 48
  • 64
Timur
  • 488
  • 4
  • 14

1 Answers1

4

PSR has nothing to do with this. PSR says nothing about docblocks.

What really matters is the way that your comments are treated by phpdoc:

<?php
/**
 * Some description about this class
 *
 * @author      Mr. Anderson
 * @since       06/09/17
 * @package
 *
 */

namespace MyNamespace;

class MyClass
{
}

is treated like you have a comment for a file, but don't have a comment for an exact class MyClass, so after generating documentation there will be an error that you don't have a class description.

In second case:

<?php

namespace MyNamespace;

/**
 * Some description about this class
 *
 * @author      Mr. Anderson
 * @since       06/09/17
 * @package
 *
 */

class MyClass
{
}

phpdoc will consider docblock as comment to a class Myclass, but will not find comment to a full file. So you will still have an error after generating docs.

But, with both of this approaches I would select second, because it is better to have class description, then file description.

u_mulder
  • 54,101
  • 5
  • 48
  • 64
  • As hinted by @u_mulder, phpDocumentor expects to see *both* the file-level docblock (his first example) *and* the class-level docblock (his second example)... so I suggest using both. If you want to specifically document the namespace itself, that docblock should come after the file-level docblock, before the namespace line itself. – ashnazg Sep 08 '17 at 10:42