Phpdoc No Summary found for this file - php

Question

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 <gbloggs#email.com>
*/
?>

Answer 1

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.

Answer 2

#ashnazg is right but I want to improve your answer with an example.
A File-level DocBlock should be the first docblock and must have a Summary (in this example the summary is "Class Category | core/Category.class.php").
Then a Class-level DocBlock is placed before a class definition.
<?php
/**
* Class Category | core/Category.class.php
*
* #package MyApp XYZ
* #subpackage Categories
* #author Sandro Miguel Marques <sandromiguel#something.com>
* #version v.1.1 (06/12/2016)
* #copyright Copyright (c) 2016, Sandro
*/
namespace Myapp;
use \PDO;
use \Exception;
use \PDOException;
/**
* Class Category - active record
*
* Recipe categories
*/
class Category {
...

Answer 3

So after a lot of searching on the server, I have a semi-fix for the problem should anyone else be encountering the same issue.
I've found out how to hide the error from the documentation, but not what is causing it.
If the error you are receiving is on Line 0, and is no summary found for this file, then you will need to edit the following file:
phpDocumentor/src/phpDocumentor/Plugin/Core/Transformer/Writer/xml.php
You will then need to search for the protected method: createErrorEntry()
This is what the existing method looks like:
protected function createErrorEntry($error, $parse_errors)
{
$marker_obj = new \DOMElement(strtolower($error->getSeverity()));
$parse_errors->appendChild($marker_obj);
$message = ($this->getTranslator())
? vsprintf($this->getTranslator()->translate($error->getCode()), $error->getContext())
: $error->getCode();
$marker_obj->appendChild(new \DOMText($message));
$marker_obj->setAttribute('line', $error->getLine());
$marker_obj->setAttribute('code', $error->getCode());
}
This method needs to have an IF condition added. Wrap the entire body of the method in the following IF condition:
protected function createErrorEntry($error, $parse_errors)
{
if($error->getCode()!=='PPC:ERR-50000')
{
$marker_obj = new \DOMElement(strtolower($error->getSeverity()));
$parse_errors->appendChild($marker_obj);
$message = ($this->getTranslator())
? vsprintf($this->getTranslator()->translate($error->getCode()), $error->getContext())
: $error->getCode();
$marker_obj->appendChild(new \DOMText($message));
$marker_obj->setAttribute('line', $error->getLine());
$marker_obj->setAttribute('code', $error->getCode());
}
}
This will stop the error being recorded, in effect, it hides the error from the end user, it doesn't fix what I can only assume is a bug in phpDocumentor. So the original error still exists, it just hasn't been recorded.
One thing I did note while debugging, is the vsprintf() function produces an error for on the PPC:ERR-50000 error. The vsprintf() produces the error PHP Warning: vsprintf(): Too few arguments. If i find out how to fix the code to stop the false error (or fix the comments to ensure the error isn't given reason to log), I'll post it here.

Answer 4

For what it's worth, I've found that creating the documentation from the commandline using parameters rather than using parameters in :
phpdoc -d ./ -t ./docs --ignore=vendor/*
vs parameters in a phpdoc.dist.xml configuration file has resolved all of the issues raised in this thread.
I don't think this stops the need for two docblocks at the top of files but it does appear to resolve the "No summary was found for this file" error when building the documentation.

Answer 5

I got the same error because I use PHP > 7 and PHPDocumentor did not recognize the syntax, so this "default error" was provided.
In my code, PHPDocumentor isn't able to parse null returns (?) in functions.
I solved this issue going to this link
https://github.com/phpDocumentor/phpDocumentor/releases
I wgot the "PHP-7 Syntax support" and installed it
wget https://github.com/phpDocumentor/phpDocumentor/releases/download/v2.9.0/phpDocumentor.phar
sudo mv phpDocumentor.phar /usr/local/bin/phpdoc
sudo chmod +x /usr/local/bin/phpdoc
check version:
phpdoc --version
= phpDocumentor version v2.9.0
It works with this phpDocumentor version

Answer 6

I got the exact same error message. I got rid of it..
the solution is very simple. in the file block at the
top, the summary line has a period at the end of it. This indicates
its a summary line.
make sure that no other blocks that follow for attributes or methods or whatever have a summary line with a period at the end. Once I removed those, the error disappeared immediately (PHPDocumentor 2.8.5)

Answer 7

I came accross this issue when my site works with php v7.4 while phpDocumentor.phar is started with php v7.2.5 and there where strong typed properties in my class. Strong typed properties aren't allowed before php v7.4.0.
class Template
{
/**
* #var string The template with some replacement strings
*/
private string $template;
....