Search code examples
phpxmlphpdocphpdocumentor2

phpDocumentor folder - No summary was found for this file

I have a bunch of folders in my project that I'm trying to ignore. Unfortunately, phpDocumentor appears to be trying to access some folders and getting "permission denied" errors.

Parsing C:\Users\Public\xampp\htdocs\select_user.php
PHP Warning:  file_get_contents(C:\Users\Public\xampp\htdocs\sql): failed to open stream: Permission denied in C:\Program Files\PHPStorm\PhpStorm 2017.2\plugins\phpdoc\phpDocumentor-2.9.0\vendor\phpdocumentor\reflection\src\phpDocumentor\Reflection\FileReflector.php on line 138
Parsing C:\Users\Public\xampp\htdocs\sql

Parsing C:\Users\Public\xampp\htdocs\table_plan.php
PHP Warning:  file_get_contents(C:\Users\Public\xampp\htdocs\tasks): failed to open stream: Permission denied in C:\Program Files\PHPStorm\PhpStorm 2017.2\plugins\phpdoc\phpDocumentor-2.9.0\vendor\phpdocumentor\reflection\src\phpDocumentor\Reflection\FileReflector.php on line 138
PHP Warning:  file_get_contents(C:\Users\Public\xampp\htdocs\vendor): failed to open stream: Permission denied in C:\Program Files\PHPStorm\PhpStorm 2017.2\plugins\phpdoc\phpDocumentor-2.9.0\vendor\phpdocumentor\reflection\src\phpDocumentor\Reflection\FileReflector.php on line 138
Parsing C:\Users\Public\xampp\htdocs\table_users.php
Parsing C:\Users\Public\xampp\htdocs\tasks

Warning: file_get_contents(C:\Users\Public\xampp\htdocs\tasks): failed to open stream: Permission denied in C:\Program Files\PHPStorm\PhpStorm 2017.2\plugins\phpdoc\phpDocumentor-2.9.0\vendor\phpdocumentor\reflection\src\phpDocumentor\Reflection\FileReflector.php on line 138
Parsing C:\Users\Public\xampp\htdocs\unlock_appraisal.php
Parsing C:\Users\Public\xampp\htdocs\util.php
Parsing C:\Users\Public\xampp\htdocs\vendor

I'm trying to exclude these directories via phpdoc.dist.xml.

<?xml version="1.0" encoding="UTF-8" ?>
<phpdoc>
    <parser>
        <target>docs/phpdoc</target>
    </parser>
    <transformer>
        <target>docs/phpdoc</target>
    </transformer>
    <files>
        <directory>*</directory>
        <file>*</file>
        <ignore>test/*</ignore>
        <ignore>assets/*</ignore>
        <ignore>doc/*</ignore>
        <ignore>docs/*</ignore>
        <ignore>examples/*</ignore>
        <ignore>html_sources/*</ignore>
        <ignore>logs/*</ignore>
        <ignore>vendor/*</ignore>
        <ignore>vendor/</ignore>
        <ignore>debug</ignore>
        <ignore>_do_this_for_troubleshooting/*</ignore>
        <ignore>*.pdf</ignore>
        <ignore>*.md</ignore>
        <ignore>*.json</ignore>
        <ignore>*.lock</ignore>
        <ignore>*.xml</ignore>
    </files>
</phpdoc>

The ignore list is working in such a way that items inside the excluded folders are exempt, however, the folders themselves are not. Thus, phpDocumentor attempts to read the folders as files, resulting in errors. These are also visible in the final HTML.

screenshot html

How do I ignore a folder properly? I know that I could try to use --ignore sqlbuddy/,docs/, however I'm pretty sure that it's the same as using the ignore XML tags in the config. Also, I would much rather have the ignore list in one central file than to have two separate locations - one in the command and one in the config XML.

After reading through my question another time, I see that the issue might be related to this:

        <directory>*</directory>
        <file>*</file>

There is also an interesting config documentation which I've read a bunch of times, but it doesn't appear to solve my specific issue.

Solution

  • The ignore behavior is "don't document what you see in this folder", rather than "don't scan this folder at all". I think the historical rationale for that was the folder might contain classes that are referenced in the classes you do want documented.

    I'm fairly sure you can "skip" the folders you want to ignore by changing the "directory" arg to be an explicit list of top level dirs to be scanned.