Add missing type hinting to Filter module docblocks

#1347914: Clean up API docs for Filter module is marked fixed, and even backported to D7.

phpcs tells me there are 'Missing parameter type' errors in filter.module, FilterUnitTest.php, and filter.api.php.

So I'm setting this as active.

Patch.

The last patch only changed docblocks, so I'm going to re-run the testbot.

Still applies, still no missing type hinting according to phpcs.

Still applies.

This patch is working.

Bumping to 8.1.x. Patch no longer applies.

[8.1.x-dev] Updated Patch.

Sorry, I think docs-only patches should go ASAP in HEAD. That's because they are non-invasive and they cannot break anything but, in the same time, are helping a lot the developers that are porting modules and also are improving the DX in most of IDEs.

Yes, should be 8.0.x for sure.

Patch sucessfully applied on 8.0.x
phpcs reports nothing.All looks good to be in. Thanks!

$ phpcs --standard="Drupal" --extensions="module,install,php" --report-csv core/modules/filter/ | grep -F $'Missing param\nReturn type missing'

These patches need to be reviewed VERY CAREFULLY, looking at the code, to make sure that the types that are added are correct.

The review here was not quite careful enough, and this patch is not quite right:

+++ b/core/modules/filter/filter.api.php
@@ -48,7 +48,7 @@ function hook_filter_secure_image_alter(&$image) {
- * @param $format
+ * @param object $format
  *   The format object of the format being disabled.
  */
 function hook_filter_format_disable($format) {

The type here is incorrect.

$format is actually an object of type FilterFormat. So the type should be listed as

\Drupal\filter\FilterFormatInterface

not "object".

Good catch @jhodgdon!
I see what you're talking about here. I really wonder how you could find such a small mistake. (Respect)

Fixed the patch, re-uploading.

Thanks!

Nice docs cleanup. Let's fix then the rest of module too, not only procedural functions :)

1. \Drupal\filter\Element\TextFormat::currentUser()
   

     /**
      * Wraps the current user.
      *
      * \Drupal\Core\Session\AccountInterface
      */
   

   Missing the @return tag.

2. \Drupal\filter\Plugin\FilterInterface::getHTMLRestrictions()

   @return array|FALSE
   

   Should be false (lowercase)

3. \Drupal\filter\Tests\FilterAPITest::setUp()
   Missing doc-block. Only {@inheritdoc}
4. \Drupal\filter\Tests\FilterCrudTest::verifyTextFormat()

     /**
      * Verifies that a text format is properly stored.
      */
   

   Missing @param and the function should be protected.

5. \Drupal\filter\Tests\FilterDefaultConfigTest::setUp()
   Missing doc-block. Only {@inheritdoc}
6. \Drupal\filter\Tests\FilterFormatAccessTest::setUp()
   Missing doc-block. Only {@inheritdoc}
7. \Drupal\filter\Tests\FilterFormTest::$adminUser
   and
   \Drupal\filter\Tests\FilterFormTest::$webUser

   @var \Drupal\user\Entity\User
   

   Both should be \Drupal\user\UserInterface

8. \Drupal\filter\Tests\FilterHtmlImageSecureTest::setUp()
   Missing doc-block. Only {@inheritdoc}
9. \Drupal\filter\Tests\FilterSecurityTest::setUp()
   Missing doc-block. Only {@inheritdoc}
10. \Drupal\filter\Tests\FilterUnitTest::setUp()
    Missing doc-block. Only {@inheritdoc}
11. \Drupal\filter\Tests\FilterUnitTest::assertFilteredString()

    /**
       * Asserts multiple filter output expectations for multiple input strings.
       *
       * @param FilterInterface $filter
       *   A input filter object.
       * @param $tests
       *   An associative array, whereas each key is an arbitrary input string and
       *   each value is again an associative array whose keys are filter output
       *   strings and whose values are Booleans indicating whether the output is
       *   expected or not.
       *
    ...
       */
    

    FilterInterface should be full qualified. @param $tests missing typehint.

12. \Drupal\filter\FilterFormatInterface::getHtmlRestrictions()
    @return array|FALSE
    Should be false (lowercase)
13. \Drupal\filter\FilterProcessResult::setProcessedText()
    @return $this
    This is wrong. We should show the type-hint not the value. Replace $this with \Drupal\filter\FilterProcessResult
14. \Drupal\Tests\filter\Unit\Plugin\migrate\source\d6\FilterFormatTest::PLUGIN_CLASS
    \Drupal\Tests\filter\Unit\Plugin\migrate\source\d6\FilterFormatTest::$migrationConfiguration
    \Drupal\Tests\filter\Unit\Plugin\migrate\source\d6\FilterFormatTest::$expectedResults
    Missing doc-block.
15. \Drupal\Tests\filter\Unit\Plugin\migrate\source\d7\FilterFormatTest::PLUGIN_CLASS
    \Drupal\Tests\filter\Unit\Plugin\migrate\source\d7\FilterFormatTest::$migrationConfiguration
    \Drupal\Tests\filter\Unit\Plugin\migrate\source\d7\FilterFormatTest::$expectedResults
    Missing doc-block.

Regarding #23, this issue needs to stay focused ONLY on fixing missing type hinting, not in fixing up other problems in doc blocks. See
https://www.drupal.org/core/scope

It doesn't look like the issues raised in #23 are in scope for this issue. Please open separate issues for them... although several are incorrect. For instance, we do want to have doc blocks that are just "inheritdoc" and @return $this is correct to use... Please take a look at https://www.drupal.org/node/1354 for documentation standards and read the Issue Scope page linked above before filing more issues about those items... thanks!

Meanwhile, this issue is complete for its scope. See #19 where the coder rule came up clean...

Committed/pushed to 8.1.x and cherry-picked to 8.0.x, thanks!