Missing function doc comment

[bgkavinga]

I am getting following code sniffer error, even though I have functional doc comments properly:

phpcs: Magento.Annotations.RequireAnnotatedMethods.Missing: Missing function doc comment (at line 28) Also checked this with Magento core classes and it gives the same error. I am using provided standards under dev/tests/static folder.

[Vinai]

I ran into a potential reason for this yesterday: the PHP opcache extension can be configured to not save phpdoc blocks, or to not load them from the cache even if they are present there.

opcache.save_comments boolean If disabled, all documentation comments will be discarded from the opcode cache to reduce the size of the optimised code. Disabling this configuration directive may break applications and frameworks that rely on comment parsing for annotations, including Doctrine, Zend Framework 2 and PHPUnit.

The value of opcache.save_comments has to be 1 for Magento 2 to work.

opcache.load_comments boolean If disabled, documentation comments won't be loaded from the opcode cache even if they exist. This can be used with opcache.save_comments to only load comments for applications that require them.

The value of opcache.load_comments has to be 1 for Magento 2 to work.

Maybe you want to check those settings values in your system for php cli? If this does not apply to you, the I don't know what might be causing the issue.

Regardless if this applies to you or not, this probably should be added to the prerequisites or troubleshooting section of the installation manual, and could also be added to the Magento-ready-check.

[bgkavinga]

@Vinai I do not have opcache enabled in my setup. It gives the same error even if I run it as unit test. (dev/tests/static)

[tkn98]

I have opcache and both values set to one (1):

$ php -i | grep opcache | grep comments
opcache.load_comments => 1 => 1
opcache.save_comments => 1 => 1

I also get the following error message:

 phpcs: Magento.Annotations.RequireAnnotatedAttributes.Missing: Missing variable doc comment

I assume it is in the same context as the reported one which I get as well:

phpcs: Magento.Annotations.RequireAnnotatedMethods.Missing: Missing function doc comment

Running phpcs on the command-line manually by specifying the standard does not show these false positives

vendor/bin/phpcs --standard=dev/tests/static/framework/Magento path/to/file.php

I therefore assume this is a cache invalidation issue within Phpstorm itself. So I did File -> Invalidate Caches / Restart ... but it didn't help.

[tkn98]

I found something here. I only had this problem within Phpstorm. That already was a hint on configuration and so it was. The PHP Code Sniffer (phpcs) path needs to be set to the command src/vendor/bin/phpcs within the project.

With my setup it was set to the global one as I had a done a composer global PHPCS installation in the past.

This fixed my issue. Next to configuration I've not done anything further, I wonder a bit that the path of the PHPCS command makes a difference, but I consider the change of configuration a valid workaround so far unless more information becomes visible.

So for troubleshooting:

1. Check that opcache supports comments.
2. Verify to use PHPCS from the project, not globally.

[tkn98]

@bgkavinga: If you still have the issue, please see my last comment and report back if that solves your issue or not.

[bgkavinga]

@tkn98 Yes, It solved my issue. Thank You.

[czettnersandor]

I found this issue by having the same problem with phpcs. I used global phpcs, when I switched to phpcs supplied in the Magento installation directory, it's giving me the same error.

First, I had to give it executable flag:

chmod u+x magento-versions/magento-CE-2.1.1/vendor/bin/phpcs

When I run it:

$ magento-versions/magento-CE-2.1.1/vendor/bin/phpcs ./paybyfinance-m2/ --standard=magento-versions/magento-CE-2.1.1/dev/tests/static/testsuite/Magento/Test/Php/_files/phpcs/ruleset.xml

I get back these results:

FILE: ...-pbf-testing/paybyfinance-m2/dev/tests/unit/pbf/presenceTest.php
----------------------------------------------------------------------
FOUND 2 ERRORS AFFECTING 2 LINES
----------------------------------------------------------------------
  8 | ERROR | [x] Opening brace of a class must be on the line after
    |       |     the definition
 10 | ERROR | [x] Opening brace should be on a new line
----------------------------------------------------------------------
PHPCBF CAN FIX THE 2 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------

FILE: .../sandor/Projects/mg2-pbf-testing/paybyfinance-m2/Helper/Data.php
----------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------
 15 | ERROR | Missing function doc comment
----------------------------------------------------------------------

FILE: ...Projects/mg2-pbf-testing/paybyfinance-m2/Setup/InstallSchema.php
----------------------------------------------------------------------
FOUND 2 ERRORS AFFECTING 2 LINES
----------------------------------------------------------------------
  23 | ERROR | Missing function doc comment
 149 | ERROR | Code must not contain multiple empty lines in a row;
     |       | found 2 empty lines
----------------------------------------------------------------------

Time: 24591459 mins, 13.14 secs; Memory: 6Mb

Around line 23 of Setup/InstallSchema.php looks like this:

    /**
     * install tables
     *
     * @param SchemaSetupInterface $setup
     * @param ModuleContextInterface $context
     * @return void
     * @SuppressWarnings(PHPMD.ExcessiveMethodLength)
     */
    public function install(SchemaSetupInterface $setup, ModuleContextInterface $context)
    {
        $installer = $setup;
        $installer->startSetup();

Also, Data.php function comment is present:

    /**
     * Constructor method
     *
     * @param \Magento\Framework\App\Helper\Context $context
     */
    public function __construct(\Magento\Framework\App\Helper\Context $context)
    {
        parent::__construct($context);

I'll take a look into the Sniffs code but it looks like to me it's definitely a bug.

[gtsiou]

This is a bug and caused by the fact that Magento is using an older version of phpcs (1.5.6 for me at 2.1.6) and the global one I have for example is 2.6.2. Anything > 2 will break it actually.

I guess there were some backwards compatibility issues there with CodeSniffer so all M2 testsuite tests fail. On the bright side, the MEQP2 Standars works fine with phpcs --version > 2.0

As @tkn98 mentions, you can either run from within Magento, or downgrade your global phpcs. Both will work.