Phpdoc No Summary found for this file

php phpdoc
Phil Cross picture Phil Cross · Jan 23, 2014 · Viewed 16.9k times · Source

I've installed phpDoc on our server, set up etc. It's producing documentation correctly. We're using the 'Responsive' template, however this error occurs regardless of the template used.

Under the 'Errors', each file scanned seems to have the following error:

Type        Line    Description
error       0       No summary was found for this file

I've googled exhaustively for this, and can't find a solution. I've even gone through the effort of tracking down the server error code behind the message PPC:ERR-50000 and attempting to track back the condition which causes the error, but got a bit lost.

My Question:

What does this error mean? Why is it on line 0, and how the hell do I get rid of it?! Even if I have done the docblock correctly, can I hide this error? My error-free ocd is going crazy!

Many thanks

EDIT Some extra information: Each of my files have the following docblock from line 1 of the file:

<?php 
    /**
     * Short Description
     *
     * Long Description
     *
     * @package      Some Package
     * @subpackage   Some Subpackage
     * @category     Some Category
     * @author       F Bloggs <[email protected]>
     */
?>

Answer

ashnazg picture ashnazg · Jan 28, 2014

But does the top of your file have two such docblocks? The first docblock is expected to be the one for the file itself, and a second docblock should pair up with the first documentable code element that appears after it.

However, if you only have one docblock at the top of the file, it will get paired up with the first code element found, thus the "file itself" will seem to be missing its docblock. That is what that error is supposed to indicate.

Related questions

PHPDoc type hinting for array of objects?

So, in PHPDoc one can specify @var above the member variable declaration to hint at its type. Then an IDE, for ex. PHPEd, will know what type of object it's working with and will be able to provide a code …

Read More
PHP Function Comments

Just a quick question: I've seen that some PHP functions are commented at the top, using a format that is unknown to me: /** * * Convert an object to an array * * @param object $object The object to convert * @return array * */ My IDE …

Read More
Best way to document Array options in PHPDoc?

I'm struggling to write readable and easy to understand documentation that describes the multi-tree structure for Array options that are passed to a function. Here is an example array structure. $arr = [ 'fields' => [ 'title' => [ 'name' => 'Document.title', 'format' =&…

Read More