search

Yoast / yoast-acf-analysis

WordPress plugin that adds the content of all ACF fields to the Yoast SEO score analysis.
https://wordpress.org/plugins/acf-content-analysis-for-yoast-seo/
GNU General Public License v3.0
61 stars 20 forks source link

Documentation: Add/update/improve documentation #152

Closed jrfnl closed 5 years ago

jrfnl commented 6 years ago

The unit tests are currently barely documented and some of the plugin files are also missing some documentation, mostly short descriptions. It would be helpful to other developers working on this codebase to add the missing info and further improve the documentation.

Documentation errors currently thrown for the unit tests when running PHPCS without excluding these issues:

FILE: inc\ac-yoast-seo-acf-content-analysis.php
----------------------------------------------------------------------------------------------------

FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------------------------------------

 217 | ERROR | Missing short description in doc comment
     |       | (Generic.Commenting.DocComment.MissingShort)
----------------------------------------------------------------------------------------------------

FILE: inc\configuration\configuration.php
----------------------------------------------------------------------------------------------------

FOUND 3 ERRORS AFFECTING 3 LINES
----------------------------------------------------------------------------------------------------

 13 | ERROR | Missing short description in doc comment (Generic.Commenting.DocComment.MissingShort)
 18 | ERROR | Missing short description in doc comment (Generic.Commenting.DocComment.MissingShort)
 23 | ERROR | Missing short description in doc comment (Generic.Commenting.DocComment.MissingShort)
----------------------------------------------------------------------------------------------------

FILE: tests\php\unit\assets-test.php
----------------------------------------------------------------------------------------------------

FOUND 4 ERRORS AFFECTING 4 LINES
----------------------------------------------------------------------------------------------------

  8 | ERROR | Missing doc comment for class Assets_Test (Squiz.Commenting.ClassComment.Missing)
  9 | ERROR | Missing member variable doc comment (Squiz.Commenting.VariableComment.Missing)
 10 | ERROR | Missing member variable doc comment (Squiz.Commenting.VariableComment.Missing)
 28 | ERROR | Missing doc comment for function testInitHook()
    |       | (Squiz.Commenting.FunctionComment.Missing)
----------------------------------------------------------------------------------------------------

FILE: tests\php\unit\Configuration\configuration-test.php
----------------------------------------------------------------------------------------------------

FOUND 15 ERRORS AFFECTING 15 LINES
----------------------------------------------------------------------------------------------------

   9 | ERROR | Missing doc comment for class Configuration_Test
     |       | (Squiz.Commenting.ClassComment.Missing)
  27 | ERROR | Missing doc comment for function testEmpty()
     |       | (Squiz.Commenting.FunctionComment.Missing)
  52 | ERROR | Missing doc comment for function testACF5VersionFunction()
     |       | (Squiz.Commenting.FunctionComment.Missing)
  66 | ERROR | Missing doc comment for function testBlacklistTypeFilter()
     |       | (Squiz.Commenting.FunctionComment.Missing)
  87 | ERROR | Missing doc comment for function testBlacklistTypeFilterInvalid()
     |       | (Squiz.Commenting.FunctionComment.Missing)
 105 | ERROR | Missing doc comment for function testBlacklistNameFilter()
     |       | (Squiz.Commenting.FunctionComment.Missing)
 125 | ERROR | Missing doc comment for function testLegacyBlackistNameFilter()
     |       | (Squiz.Commenting.FunctionComment.Missing)
 159 | ERROR | Missing doc comment for function testLegacyBlackistNameFilterInvalid()
     |       | (Squiz.Commenting.FunctionComment.Missing)
 184 | ERROR | Missing doc comment for function testBlacklistNameFilterInvalid()
     |       | (Squiz.Commenting.FunctionComment.Missing)
 202 | ERROR | Missing doc comment for function testScraperConfigFilter()
     |       | (Squiz.Commenting.FunctionComment.Missing)
 220 | ERROR | Missing doc comment for function testInvalidScraperConfigFilter()
     |       | (Squiz.Commenting.FunctionComment.Missing)
 237 | ERROR | Missing doc comment for function testRefreshRateFilter()
     |       | (Squiz.Commenting.FunctionComment.Missing)
 252 | ERROR | Missing doc comment for function testRefreshRateMinimumValueFilter()
     |       | (Squiz.Commenting.FunctionComment.Missing)
 267 | ERROR | Missing doc comment for function testFieldSelectorsFilter()
     |       | (Squiz.Commenting.FunctionComment.Missing)
 285 | ERROR | Missing doc comment for function testFieldSelectorsFilterInvalid()
     |       | (Squiz.Commenting.FunctionComment.Missing)
----------------------------------------------------------------------------------------------------

FILE: tests\php\unit\Configuration\string-store-test.php
----------------------------------------------------------------------------------------------------

FOUND 11 ERRORS AFFECTING 11 LINES
----------------------------------------------------------------------------------------------------

   6 | ERROR | Missing doc comment for class String_Store_Test
     |       | (Squiz.Commenting.ClassComment.Missing)
   8 | ERROR | Missing short description in doc comment
     |       | (Generic.Commenting.DocComment.MissingShort)
  15 | ERROR | Missing doc comment for function testEmpty()
     |       | (Squiz.Commenting.FunctionComment.Missing)
  20 | ERROR | Missing doc comment for function testAdd()
     |       | (Squiz.Commenting.FunctionComment.Missing)
  31 | ERROR | Missing doc comment for function testAddSame()
     |       | (Squiz.Commenting.FunctionComment.Missing)
  43 | ERROR | Missing doc comment for function testAddMultiple()
     |       | (Squiz.Commenting.FunctionComment.Missing)
  56 | ERROR | Missing doc comment for function testAddMultipleSorting()
     |       | (Squiz.Commenting.FunctionComment.Missing)
  69 | ERROR | Missing doc comment for function testAddNonString()
     |       | (Squiz.Commenting.FunctionComment.Missing)
  78 | ERROR | Missing doc comment for function testRemove()
     |       | (Squiz.Commenting.FunctionComment.Missing)
 100 | ERROR | Missing doc comment for function testRemoveNonString()
     |       | (Squiz.Commenting.FunctionComment.Missing)
 109 | ERROR | Missing doc comment for function testRemoveNonExist()
     |       | (Squiz.Commenting.FunctionComment.Missing)
----------------------------------------------------------------------------------------------------

FILE: tests\php\unit\Dependencies\acf-dependency-test.php
----------------------------------------------------------------------------------------------------

FOUND 4 ERRORS AFFECTING 4 LINES
----------------------------------------------------------------------------------------------------

  7 | ERROR | Missing doc comment for class ACF_Dependency_Test
    |       | (Squiz.Commenting.ClassComment.Missing)
 24 | ERROR | Missing doc comment for function testNoACFClassExists()
    |       | (Squiz.Commenting.FunctionComment.Missing)
 30 | ERROR | Missing doc comment for function testACFClassExists()
    |       | (Squiz.Commenting.FunctionComment.Missing)
 38 | ERROR | Missing doc comment for function testAdminNotice()
    |       | (Squiz.Commenting.FunctionComment.Missing)
----------------------------------------------------------------------------------------------------

FILE: tests\php\unit\Dependencies\yoast-seo-dependency-test.php
----------------------------------------------------------------------------------------------------

FOUND 8 ERRORS AFFECTING 8 LINES
----------------------------------------------------------------------------------------------------

  7 | ERROR | Missing doc comment for class Yoast_SEO_Dependency_Test
    |       | (Squiz.Commenting.ClassComment.Missing)
  8 | ERROR | Missing member variable doc comment (Squiz.Commenting.VariableComment.Missing)
  9 | ERROR | Missing member variable doc comment (Squiz.Commenting.VariableComment.Missing)
 27 | ERROR | Missing doc comment for function testFail()
    |       | (Squiz.Commenting.FunctionComment.Missing)
 33 | ERROR | Missing doc comment for function testPass()
    |       | (Squiz.Commenting.FunctionComment.Missing)
 40 | ERROR | Missing doc comment for function testOldVersion()
    |       | (Squiz.Commenting.FunctionComment.Missing)
 47 | ERROR | Missing doc comment for function testAdminNotice()
    |       | (Squiz.Commenting.FunctionComment.Missing)
 54 | ERROR | Missing doc comment for function testAdminNoticeMinimumVersion()
    |       | (Squiz.Commenting.FunctionComment.Missing)
----------------------------------------------------------------------------------------------------

FILE: tests\php\unit\Doubles\failing-dependency.php
----------------------------------------------------------------------------------------------------

FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------------------------------------

 5 | ERROR | Missing doc comment for class Failing_Dependency
   |       | (Squiz.Commenting.ClassComment.Missing)
----------------------------------------------------------------------------------------------------

FILE: tests\php\unit\Doubles\passing-dependency.php
----------------------------------------------------------------------------------------------------

FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------------------------------------

 5 | ERROR | Missing doc comment for class Passing_Dependency
   |       | (Squiz.Commenting.ClassComment.Missing)
----------------------------------------------------------------------------------------------------

FILE: tests\php\unit\main-test.php
----------------------------------------------------------------------------------------------------

FOUND 2 ERRORS AFFECTING 2 LINES
----------------------------------------------------------------------------------------------------

  7 | ERROR | Missing doc comment for class Main_Test (Squiz.Commenting.ClassComment.Missing)
 25 | ERROR | Missing doc comment for function testInvalidConfig()
    |       | (Squiz.Commenting.FunctionComment.Missing)
----------------------------------------------------------------------------------------------------

FILE: tests\php\unit\registry-test.php
----------------------------------------------------------------------------------------------------

FOUND 3 ERRORS AFFECTING 3 LINES
----------------------------------------------------------------------------------------------------

  6 | ERROR | Missing doc comment for class Registry_Test (Squiz.Commenting.ClassComment.Missing)
  8 | ERROR | Missing doc comment for function testSingleton()
    |       | (Squiz.Commenting.FunctionComment.Missing)
 28 | ERROR | Missing doc comment for function testAdd() (Squiz.Commenting.FunctionComment.Missing)
----------------------------------------------------------------------------------------------------

FILE: tests\php\unit\requirements-test.php
----------------------------------------------------------------------------------------------------

FOUND 5 ERRORS AFFECTING 5 LINES
----------------------------------------------------------------------------------------------------

 12 | ERROR | Missing doc comment for class Requirements_Test
    |       | (Squiz.Commenting.ClassComment.Missing)
 32 | ERROR | Missing doc comment for function testNoDependencies()
    |       | (Squiz.Commenting.FunctionComment.Missing)
 37 | ERROR | Missing doc comment for function testPassingDependency()
    |       | (Squiz.Commenting.FunctionComment.Missing)
 44 | ERROR | Missing doc comment for function testFailingDependency()
    |       | (Squiz.Commenting.FunctionComment.Missing)
 51 | ERROR | Missing doc comment for function testMixedDependencies()
    |       | (Squiz.Commenting.FunctionComment.Missing)
----------------------------------------------------------------------------------------------------
moorscode commented 6 years ago

While solving the problems, the temporary exclusions and error to warning conversions need to be removed from the PHPCS configuration.

jrfnl commented 6 years ago

While solving the problems, the temporary exclusions and error to warning conversions need to be removed from the PHPCS configuration.

I'm presuming/hoping you mean this :point_down: ?

"To see an up-to-date list of the issues, comment out the temporary exclusions and error to warning conversions before running PHPCS. Once the documentation issues are completely fixed, the related temporary exclusions and error to warning conversions should be removed from the PHPCS ruleset."

jrfnl commented 5 years ago

This is the part of the ruleset, the above two comments relate to:

https://github.com/Yoast/yoast-acf-analysis/blob/8fb1310727a0acdc4b81a9314a80ec0fbd60ca67/.phpcs.xml.dist#L125-L138