Skip to content
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.

Sign up for GitHub

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

Jump to bottom

XML Documentation xsd and samples how it could look like #2

Closed
wants to merge 3 commits into from
Closed

XML Documentation xsd and samples how it could look like #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4f55a01
Minor additions to the sniff XML documentation and a xsd to check aga…
edorian Nov 8, 2011
0911742
Adapting the wording after some discussion on https://github.com/squi…
edorian Nov 9, 2011
eff40f0
Adapting the wording after some discussion on https://github.com/squi…
edorian Nov 11, 2011
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
23 changes: 21 additions & 2 deletions CodeSniffer/Standards/Generic/Docs/Files/LineLengthStandard.xml
View file
Open in desktop
@@ -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">
Copy link
Member

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.

Copy link
Contributor Author

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 :)

<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.
Copy link
Member

Choose a reason for hiding this comment

The 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:
"It is recommended to keep lines at approximately 80 characters long for better code readability and lines should never exceed 0 characters."

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>
21 changes: 20 additions & 1 deletion CodeSniffer/Standards/Generic/Docs/Formatting/MultipleStatementAlignmentStandard.xml
View file
Open in desktop
@@ -1,4 +1,23 @@
<documentation title="Aligning Blocks of Assignments">
<?xml version="1.0" encoding="UTF-8" ?>
<documentation title="Aligning Blocks of Assignments" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../tests/documentation.xsd">
<properties>
<property name="maxPadding" type="integer" default="1000">
<description>
<![CDATA[
The maximum amount of padding before the alignment is ignored.

If the amount of padding required to align this assignment with the surrounding assignments exceeds this number, the assignment will be ignored and no errors or warnings will be thrown.
]]>
</description>
</property>
<property name="maxPadding" type="boolean" default="false">
<description>
<![CDATA[
If true, multi-line assignments are not checked.
]]>
</description>
</property>
</properties>
<standard>
<![CDATA[
There should be one space on either side of an equals sign used to assign a value to a variable. In the case of a block of related assignments, more space may be inserted to promote readability.
Expand Down
3 changes: 2 additions & 1 deletion CodeSniffer/Standards/Generic/Docs/Functions/OpeningFunctionBraceBsdAllmanStandard.xml
View file
Open in desktop
@@ -1,4 +1,5 @@
<documentation title="Opening Brace in Function Declarations">
<?xml version="1.0" encoding="UTF-8" ?>
<documentation title="Opening Brace in Function Declarations" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../tests/documentation.xsd">
<standard>
<![CDATA[
Function declarations follow the "BSD/Allman style". The function brace is on the line following the function declaration and is indented to the same column as the start of the function declaration.
Expand Down
3 changes: 2 additions & 1 deletion ...Sniffer/Standards/Generic/Docs/Functions/OpeningFunctionBraceKernighanRitchieStandard.xml
View file
Open in desktop
@@ -1,4 +1,5 @@
<documentation title="Opening Brace in Function Declarations">
<?xml version="1.0" encoding="UTF-8" ?>
<documentation title="Opening Brace in Function Declarations" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../tests/documentation.xsd">
<standard>
<![CDATA[
Function declarations follow the "Kernighan/Ritchie style". The function brace is on the same line as the function declaration. One space is required between the closing parenthesis and the brace.
Expand Down
3 changes: 2 additions & 1 deletion CodeSniffer/Standards/Generic/Docs/NamingConventions/UpperCaseConstantNameStandard.xml
View file
Open in desktop
@@ -1,4 +1,5 @@
<documentation title="Constant Names">
<?xml version="1.0" encoding="UTF-8" ?>
<documentation title="Constant Names" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../tests/documentation.xsd">
<standard>
<![CDATA[
Constants should always be all-uppercase, with underscores to separate words.
Expand Down
17 changes: 16 additions & 1 deletion CodeSniffer/Standards/Generic/Docs/PHP/DisallowShortOpenTagStandard.xml
View file
Open in desktop
@@ -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>
3 changes: 2 additions & 1 deletion CodeSniffer/Standards/Generic/Docs/PHP/LowerCaseConstantStandard.xml
View file
Open in desktop
@@ -1,4 +1,5 @@
<documentation title="PHP Constants">
<?xml version="1.0" encoding="UTF-8" ?>
<documentation title="PHP Constants" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../tests/documentation.xsd">
<standard>
<![CDATA[
The <em>true</em>, <em>false</em> and <em>null</em> constants must always be lowercase.
Expand Down
3 changes: 2 additions & 1 deletion CodeSniffer/Standards/Generic/Docs/PHP/UpperCaseConstantStandard.xml
View file
Open in desktop
@@ -1,4 +1,5 @@
<documentation title="PHP Constants">
<?xml version="1.0" encoding="UTF-8" ?>
<documentation title="PHP Constants" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../tests/documentation.xsd">
<standard>
<![CDATA[
The <em>true</em>, <em>false</em> and <em>null</em> constants must always be uppercase.
Expand Down
9 changes: 5 additions & 4 deletions CodeSniffer/Standards/Generic/Sniffs/Files/LineLengthSniff.php
View file
Open in desktop
Expand Up @@ -14,11 +14,12 @@
*/

/**
* Generic_Sniffs_Files_LineLengthSniff.
* Checks all lines in the file and shows warnings or errors if they are too long
*
* 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.
*
* 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.
* Both these limits can be changed in your standard's ruleset file, or when extending the sniff.
*
* @category PHP
* @package PHP_CodeSniffer
Expand Down
54 changes: 54 additions & 0 deletions tests/documentation.xsd
View file
Open in desktop
@@ -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>