Problem/Motivation

The Drupal 8 coding standard guide states

The @file doc block MUST be present for all PHP files, with one exception: files that contain a namespaced class/interface/trait, whose file name is the class name with a .php extension, and whose file path is closely related to the namespace (under PSR-4 or a similar standard), SHOULD NOT have a @file documentation block.

We see this violated throughout Examples.

Proposed resolution

See the parent issue for instructions on how to install phpcs.

  • Add the Drupal.Commenting.FileComment.NamespaceNoFileDoc sniff as a rule to phpcs.xml.dist.
  • Run phpcfb to make automated changes.
  • Review the changes made by phpcbf.
  • Run phpcs in order to verify that the error no longer exists.
  • Submit a patch with all changed files, remembering to include the changes to phpcs.xml.dist in the patch.

To Review

To review this issue you should:

How to run phpcs?

If you've installed phpcs as per the instructions in the meta, you can then change directories into the examples module and use .. to execute the phpcs executable you just installed. Like this:

$ pwd
/PATH/TO/drupal/modules/examples

$ ../../vendor/bin/phpcs -p -s

[ ...phpcs results print out... ]
CommentFileSizeAuthor
#15 interdiff.txt1.03 KBmile23
#11 interdiff.txt630 bytesimalabya
#11 2735851-11.patch41.94 KBimalabya
#8 2735851-8.patch41.27 KBimalabya
#6 2735851-6.patch41.62 KBimalabya
no-file-doc-before-namespace.patch2.77 KBimalabya

Comments

malavya created an issue. See original summary.

imalabya’s picture

imalabya
Primary language English
Location Bangalore
commented
Status: Active » Needs review
mile23’s picture

mile23
Primary language English
Location Seattle, WA
commented
Title: Remove @file doc from Namespaced classes, interfaces and traits » Fix Drupal.Commenting.FileComment.NamespaceNoFileDoc for Examples
Issue summary: View changes
Status: Needs review » Needs work
Parent issue: » #2176147: [meta] Coding standards review for D8 Examples

Thanks for the issue and the patch. I'm re-scoping this a little to include the parent issue and instructions on how to make all the changes semiautomatically.

mile23’s picture

mile23
Primary language English
Location Seattle, WA
commented
Issue summary: View changes
mile23’s picture

mile23
Primary language English
Location Seattle, WA
commented
Issue summary: View changes
imalabya’s picture

imalabya
Primary language English
Location Bangalore
commented
StatusFileSize
new 2735851-6.patch41.62 KB

Hi Miles23, here is an updated patch for the sniffs. The method really helped to make it quick. Please review if everything looks good. Not adding any interdiff as it's a new patch with the old changes as well.

imalabya’s picture

imalabya
Primary language English
Location Bangalore
commented
Status: Needs work » Needs review
imalabya’s picture

imalabya
Primary language English
Location Bangalore
commented
StatusFileSize
new 2735851-8.patch41.27 KB

Uploading the patch, removed composer.json changes which were added by mistake.

mile23’s picture

mile23
Primary language English
Location Seattle, WA
commented
Issue summary: View changes

Updating issue summary with review instructions.

mile23’s picture

mile23
Primary language English
Location Seattle, WA
commented
Status: Needs review » Needs work

Nice. Except for one thing:

+++ b/config_entity_example/src/Entity/Robot.php
@@ -1,15 +1,5 @@
- * Originally based on code from blog post at
- * http://previousnext.com.au/blog/understanding-drupal-8s-config-entities

Move this comment to an appropriate place in config_entity_example.module's @defgroup block.

imalabya’s picture

imalabya
Primary language English
Location Bangalore
commented
StatusFileSize
new 2735851-11.patch41.94 KB
new interdiff.txt630 bytes

Here is the updated patch and interdiff.

imalabya’s picture

imalabya
Primary language English
Location Bangalore
commented
Status: Needs work » Needs review
mile23’s picture

mile23
Primary language English
Location Seattle, WA
commented
Status: Needs review » Needs work

Thanks!

+++ b/cron_example/src/Tests/CronExampleTestCase.php
@@ -1,15 +1,5 @@
-
-/**
- * @addtogroup cron_example
- * @{
- */
-

Oh, didn't notice this before, sorry.

I think this is a good change, since the class itself is tagged @ingroup. But that leaves the @} at the end of the file, which needs to be removed.

After that, we only have these two:

FILE: ...hum/projects/drupal8/modules/examples/src/Tests/ExamplesTest.php
----------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------
 3 | ERROR | [x] Namespaced classes, interfaces and traits should not
   |       |     begin with a file doc comment
   |       |     (Drupal.Commenting.FileComment.NamespaceNoFileDoc)
----------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------


FILE: ...projects/drupal8/modules/examples/src/Tests/ExamplesTestBase.php
----------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------
 3 | ERROR | [x] Namespaced classes, interfaces and traits should not
   |       |     begin with a file doc comment
   |       |     (Drupal.Commenting.FileComment.NamespaceNoFileDoc)
----------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------

  • Mile23 committed 765bfaf on 8.x-1.x authored by malavya 
    Issue #2735851 by malavya: Fix Drupal.Commenting.FileComment....
mile23’s picture

mile23
Primary language English
Location Seattle, WA
commented
Status: Needs work » Fixed
StatusFileSize
new interdiff.txt1.03 KB

Fixed the remainder on commit. Thanks!

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.