CODEWITHSUNDEEP
phpphpdocpsr-2psr-1
Timur
Timur

Reputation: 498

PSR for using description of class

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
{
}

Upvotes: 2

Views: 767

Answers (1)

u_mulder
u_mulder

Reputation: 54831

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.

Upvotes: 4

Related Questions