New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
XML Documentation xsd and samples how it could look like #2
Changes from 2 commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,7 +1,26 @@ | ||
<documentation title="Line Length"> | ||
<?xml version="1.0" encoding="UTF-8" ?> | ||
<documentation title="Line Length" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../tests/documentation.xsd"> | ||
<properties> | ||
<property name="lineLimit" type="integer" default="80"> | ||
<description> | ||
<![CDATA[ | ||
The limit that the length of a line should not exceed. | ||
]]> | ||
</description> | ||
</property> | ||
<property name="absoluteLineLimit" type="integer" default="100"> | ||
<description> | ||
<![CDATA[ | ||
The limit that the length of a line must not exceed. | ||
|
||
Set to zero (0) to disable. | ||
]]> | ||
</description> | ||
</property> | ||
</properties> | ||
<standard> | ||
<![CDATA[ | ||
It is recommended to keep lines at approximately 80 characters long for better code readability. | ||
It is recommended to keep lines at approximately {lineLimit} characters long for better code readability and lines should never exceed {absoluteLineLimit} characters. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thinking more about it, this isn't gong to work. If you have disabled your absoluteLineLimit (set it to zero) then the message will show: We obviously need to devise a smarter system that allows documentation to be generated based on the values that the project-specific standard is setting. |
||
]]> | ||
</standard> | ||
</documentation> |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,7 +1,22 @@ | ||
<documentation title="PHP Code Tags"> | ||
<?xml version="1.0" encoding="UTF-8" ?> | ||
<documentation title="PHP Code Tags" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../tests/documentation.xsd"> | ||
<standard> | ||
<![CDATA[ | ||
Always use <?php ?> to delimit PHP code, not the <? ?> shorthand. This is the most portable way to include PHP code on differing operating systems and setups. | ||
]]> | ||
</standard> | ||
<code_comparison> | ||
<code title="Valid: file with long open tag"> | ||
<![CDATA[ | ||
<?php | ||
// contents... | ||
]]> | ||
</code> | ||
<code title="Invalid: file with short open tag"> | ||
<![CDATA[ | ||
<? | ||
// contents... | ||
]]> | ||
</code> | ||
</code_comparison> | ||
</documentation> |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -14,11 +14,10 @@ | |
*/ | ||
|
||
/** | ||
* Generic_Sniffs_Files_LineLengthSniff. | ||
* Checks all lines in the file and warnings and errors they are to long | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This should be: Checks all lines in the file and shows warnings or errors if they are too long |
||
* | ||
* Checks all lines in the file, and throws warnings if they are over 80 | ||
* characters in length and errors if they are over 100. Both these | ||
* figures can be changed by extending this sniff in your own standard. | ||
* Per default a warning is generated when the line is over 80 characters and an errors if it is over 100 characters | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This should be: Per default, a warning is generated when the line is over 80 characters and an error is generated when the line is over 100 characters. |
||
* Both these figures can be changed by extending this sniff in your own standard. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There are actually 2 ways. Either extend the sniff and produce a whole new one, or just create your own ruleset.xml file and override the values in there. For example:
We should probably come up with a standard way of saying this. Maybe: |
||
* | ||
* @category PHP | ||
* @package PHP_CodeSniffer | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,54 @@ | ||
<?xml version="1.0" encoding="UTF-8"?> | ||
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> | ||
|
||
<xs:element name="documentation" type="documentation"/> | ||
|
||
<xs:complexType name="documentation"> | ||
<xs:sequence minOccurs="1" maxOccurs="1"> | ||
<xs:element name="properties" type="properties" minOccurs="0" maxOccurs="1"/> | ||
<xs:sequence minOccurs="1" maxOccurs="unbounded"> | ||
<xs:element name="standard" type="xs:string" minOccurs="1" maxOccurs="1"/> | ||
<xs:element name="code_comparison" type="code_comparison" minOccurs="0" maxOccurs="unbounded"/> | ||
</xs:sequence> | ||
</xs:sequence> | ||
<xs:attribute name="title" type="xs:string" use="required" /> | ||
</xs:complexType> | ||
|
||
<xs:complexType name="properties"> | ||
<xs:sequence> | ||
<xs:element name="property" type="property" maxOccurs="unbounded" minOccurs="1"/> | ||
</xs:sequence> | ||
</xs:complexType> | ||
|
||
<xs:complexType name="property"> | ||
<xs:sequence> | ||
<xs:element name="description" type="xs:string" maxOccurs="1" minOccurs="1"/> | ||
</xs:sequence> | ||
<xs:attribute name="name" type="xs:string" use="required" /> | ||
<xs:attribute name="type" use="required"> | ||
<xs:simpleType> | ||
<xs:restriction base="xs:string"> | ||
<xs:enumeration value="boolean"/> | ||
<xs:enumeration value="integer"/> | ||
<xs:enumeration value="string"/> | ||
</xs:restriction> | ||
</xs:simpleType> | ||
</xs:attribute> | ||
<xs:attribute name="default" type="xs:string" use="required" /> | ||
</xs:complexType> | ||
|
||
<xs:complexType name="code_comparison"> | ||
<xs:sequence> | ||
<xs:element name="code" maxOccurs="unbounded" minOccurs="1"> | ||
<xs:complexType> | ||
<xs:simpleContent> | ||
<xs:extension base="xs:string"> | ||
<xs:attribute name="title" type="xs:string" use="required"/> | ||
</xs:extension> | ||
</xs:simpleContent> | ||
</xs:complexType> | ||
</xs:element> | ||
</xs:sequence> | ||
</xs:complexType> | ||
|
||
</xs:schema> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This schema location is incorrect. When installed, PHP_CodeSniffer puts test files in different locations than the main code files.
But the documentation schema shouldn't be in the tests directory anyway as it has nothing to do with testing. I think it should be stored with the doc generators, which should allow it to be referenced using relative paths.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah i just put them somewhere to get the ball rolling; I fully expected the file to be in the wrong place there but it was the best wrong option i could come up with :)