XML Documentation xsd and samples how it could look like #1
Conversation
…inst / work with to easy the writing of the xml
|
This looks really good, and thanks again for taking the time to get this going again. One thing I want to discuss first is the purpose of each sniff doc. Before PHP_CodeSniffer, I worked on a similar product that checked standards and it also generated a PDF doc of the standard. This was basically a reference guide for developers. This is the documentation I'd like to generate from PHP_CodeSniffer as well; a doc for the developers using the standard and not a doc for people creating standards and sniffs. That's useful documentation as well, but it is more technical documentation. The reason I bring this up is because of your change to the LineLength text. Instead of reading as a how-to for developers, it now reads as a how-to for standard developers, which I know is the intention of your interface. So maybe we can come up with a combined format, or maybe this is two different bits of documentation. The XML file could contain just the dev-focused docs and the sniff files themselves could contain the standard developer docs. Maybe an interface to create the standard could use the more technical docs from docblocks and then provide a HTML description of what the developer will see for each sniff, including the examples. If they want to use it, it can combine everything into one standard and even generate the docs for it so they can confirm they are happy. Would love to know your thoughts on this. |
|
This is an amazing idea/goal. I'd love to be able to automatically generate 'end-developer/human-readable-guidelines' from a phpcs.xml ruleset file. I surly help to make that happen as i think this increases the value of this tool a lot when getting started! The Another option would be for me to also adapt the class doc blocks while working on the xml files and use those as developer documentation (well thats what are anyways right? :) ) One change I'd like to propose then is:
into
{tags} named like properties as it's a way to keep the docs dynamic so really get docs matching YOUR settings and not just generics numbers that you need to map in your mind. Let me know your thoughts on that and I'll adopt the pull request accordingly |
|
Adapted the pull request a little in edorian@0911742 to show of what I've tried to describe. I haven't had a nicer idea for the placeholders (except using xml tags with refIds, just tell me what you'd like more) |
|
Sorry for the noise. Github doesn't seem to catch the other commit i made. I'll send a new PR |
PSR2/UseDeclaration: simplify the fix
DisallowAlternativePHPTags: remove pre-PHP 5.4 work-around
The `Util\Standards::getInstalledStandardPath()` method returns either a string or `null`, however the `strpos()` method which is used in both the `Util\Common::isPharFile()` method, as well as in the follow-on condition, only accepts a `string` as `$haystack`. As of PHP 8.1, this will generate a deprecation notice `strpos(): Passing null to parameter #1 ($haystack) of type string is deprecated`. Discovered while testing an external standard against PHPCS `master` on PHP 8.1. Fixed now.
The `Util\Standards::getInstalledStandardPath()` method returns either a string or `null`, however the `strpos()` method which is used in both the `Util\Common::isPharFile()` method, as well as in the follow-on condition, only accepts a `string` as `$haystack`. As of PHP 8.1, this will generate a deprecation notice `strpos(): Passing null to parameter #1 ($haystack) of type string is deprecated`. Discovered while testing an external standard against PHPCS `master` on PHP 8.1. Fixed now.
On PHP 8.1, passing `null` to `strtolower()` generates a `strtolower(): Passing null to parameter #1 ($string) of type string is deprecated` notice. The `File::getDeclarationName()` will return `null` for anonymous classes, so we need an extra safeguard here. This fix is covered by the existing unit tests and was exposed when running the tests on PHP 8.1 with `error_reporting` set to `E_ALL`.
On PHP 8.1, passing `null` to `strtolower()` generates a `strtolower(): Passing null to parameter #1 ($string) of type string is deprecated` notice. The `File::getDeclarationName()` will return `null` for anonymous classes, so we need an extra safeguard here. This fix is covered by the existing unit tests and was exposed when running the tests on PHP 8.1 with `error_reporting` set to `E_ALL`.
…update-for-new-home Update for Composer name + docs for new repo home
I've had a little discussed with @gsherwood about how to contribute to the sniffs documentation and he suggested to improve upon the existing xml documentation.
Should you pull this I will then start to add documentation for every sniff in "Generic".
What i mainly added was documentation for the available properties, their type and a default value.
I'm looking to improve the docs to be able to build something like http://edorian.github.com/php-coding-standard-generator/ for PHP_CodeSniffer and because I've send quite some time trying to figure out what sniffs do ;)
If you don't like the formatting just let me know, this is just an example of how it could look like :)
Credit for the xsd file goes to @gooh