[Update] Documentation for sniff WordPress.Files.FilesName #2590
Conversation
jrfnl
changed the title
There was a problem hiding this comment.
Thanks for working on this PR, @jasonkenison! I left some comments with suggestions. Let me know if you have any questions.
| </code_comparison> | ||
| <standard> | ||
| <![CDATA[ | ||
| Files in `wp-includes` containing template tags should end in `-template`. |
There was a problem hiding this comment.
I believe this description could detail a bit more which files in the wp-includes directory should end in -template. What do you think of the suggestion below? Feel free to improve it or create something different (note that this line should start with four spaces and not three).
| Files in `wp-includes` containing template tags should end in `-template`. | |
| Non-class files in the directory `wp-includes` with a "@subpackage Template" tag should use the `-template` suffix. |
| <?xml version="1.0"?> | ||
| <documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | ||
| xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd" | ||
| title="File Name Standards" |
There was a problem hiding this comment.
The title of the document should match the sniff name.
| title="File Name Standards" | |
| title="File Name" |
| <standard> | ||
| <![CDATA[ | ||
| File name must not be a mimetype sublevel only file names, such as `plain.php`. | ||
| ]]> | ||
| </standard> | ||
| <code_comparison> | ||
| <code title="Valid: Is not a mimetype only file name."> | ||
| <![CDATA[ | ||
| <em>taxonomy-term</em>.inc | ||
| <em>class-test-sample</em>.php | ||
| <em>other-punctuation</em>.inc | ||
| ]]> | ||
| </code> | ||
| <code title="Invalid: Is a mimetype only file name."> | ||
| <![CDATA[ | ||
| <em>text-plain</em>.php | ||
| <em>html</em>.inc | ||
| <em>richtext</em>.php | ||
| ]]> | ||
| </code> | ||
| </code_comparison> |
There was a problem hiding this comment.
Please correct me if I'm mistaken, but I don't think the sniff has this rule.
This can be tested using one of the invalid examples provided here to see that it does not trigger an error:
$ vendor/bin/phpcs -s --standard=WordPress --sniffs=WordPress.Files.FileName text-plain.php
$| </code_comparison> | ||
| <standard> | ||
| <![CDATA[ | ||
| Filenames should be all lowercase with hyphens separating words. If `$is_theme` property is set to `true` certain theme specific exceptions are made for underscores. |
There was a problem hiding this comment.
This is something that needs to be improved in how sniffs are documented, but currently we only mention the default behavior of the sniff, so I don't think we should mention what happens in $is_theme is set to true. Also, there should be four spaces at the start of this line.
| Filenames should be all lowercase with hyphens separating words. If `$is_theme` property is set to `true` certain theme specific exceptions are made for underscores. | |
| Filenames should be all lowercase with hyphens separating words. |
| <code title="Valid: Lowercase and `-` separators."> | ||
| <![CDATA[ | ||
| taxonomy<em>-</em>my<em>-</em>term.inc | ||
| <em>s</em>ome<em>f</em>ile.inc |
There was a problem hiding this comment.
Considering the invalid example related to this one, I believe the valid example should separate the two words with a hyphen, no? This would also fix the error in CI that is a false positive in my opinion, as ome is incorrectly being flagged as a typo.
| <em>s</em>ome<em>f</em>ile.inc | |
| some<em>-</em>file.inc |
| <![CDATA[ | ||
| taxonomy<em>-</em>my<em>-</em>term.inc | ||
| <em>s</em>ome<em>f</em>ile.inc | ||
| <em>class</em>-testsample.inc |
There was a problem hiding this comment.
I'm not sure if I understand this specific example. Why is class highlighted, considering that this specific error (NotHyphenatedLowercase) does not check for the class prefix? If this example does not add anything that is not already covered in the other examples, maybe it can be removed together with the corresponding invalid example?
| <code_comparison> | ||
| <code title="Valid: File name matches prefix and class."> | ||
| <![CDATA[ | ||
| <em>class-bulkupdater</em>.php |
There was a problem hiding this comment.
It depends on the class name, but considering that the idea is to separate words using hyphens and also considering the name of the corresponding invalid example, maybe this one should be class-bulk-updater.php?
Related to the above, maybe you can add a code comment with the class name to those examples? And then include an example where the name is invalid because the file name does not match the class name, despite it following the other formatting rules?
Then it might also make sense to include a valid example for each of the invalid examples. Maybe there should be one invalid example without the class- prefix and one where the file name is not based on the class name? Maybe there is value to add more that I'm missing.
| </code> | ||
| <code title="Invalid: File name missing prefix or class."> | ||
| <![CDATA[ | ||
| <em>class.</em>bulk-updater.php |
There was a problem hiding this comment.
I wonder if here it is not better to highlight just the dot as this is the exact part that would cause the error?
| <em>class.</em>bulk-updater.php | |
| class<em>.</em>bulk-updater.php |
| ]]> | ||
| </standard> | ||
| <code_comparison> | ||
| <code title="Valid: File name with proper prefix/suffix."> |
There was a problem hiding this comment.
Maybe remove prefix here and in the title below as this particular error is checking just for the suffix of the file and not a prefix?
Related to #1722
Continuing updates from #2492
Closes #2492