From aa9a9ac810dd149c1a868db675c0da4f5348b071 Mon Sep 17 00:00:00 2001
From: Jay McPartland <2131911+jonmcp@users.noreply.github.com>
Date: Tue, 27 Feb 2024 02:33:02 +0000
Subject: [PATCH] [Documentation] Squiz: Superfluous Whitespace (#352)

* Docs: add documentation for Squiz.WhiteSpace.SuperfluousWhitespace

* Docs: improve documentation for Squiz.WhiteSpace.SuperfluousWhitespace

- Add code comparison for a missed error code (EOF)
- Fixup CDATA indentation
- Clarify wording in code examples

* Docs: fix typo in Squiz.WhiteSpace.SuperfluousWhitespace code example

* Docs: rewrite incorrect code example for Squiz.WhiteSpace.SuperfluousWhitespace.EndFile

* Squiz/SuperfluousWhitespace: tiny tweak
---
 .../SuperfluousWhitespaceStandard.xml         | 98 +++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 src/Standards/Squiz/Docs/WhiteSpace/SuperfluousWhitespaceStandard.xml

diff --git a/src/Standards/Squiz/Docs/WhiteSpace/SuperfluousWhitespaceStandard.xml b/src/Standards/Squiz/Docs/WhiteSpace/SuperfluousWhitespaceStandard.xml
new file mode 100644
index 0000000000..b4ad03d0b4
--- /dev/null
+++ b/src/Standards/Squiz/Docs/WhiteSpace/SuperfluousWhitespaceStandard.xml
@@ -0,0 +1,98 @@
+<documentation title="Superfluous Whitespace">
+    <standard>
+    <![CDATA[
+    There should be no superfluous whitespace at the start of a file.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: No whitespace preceding first content in file.">
+        <![CDATA[<?php
+echo 'opening PHP tag at start of file';
+        ]]>
+        </code>
+        <code title="Invalid: Whitespace used before content in file.">
+        <![CDATA[
+<em>        </em>
+<?php
+echo 'whitespace before opening PHP tag';
+        ]]>
+        </code>
+    </code_comparison>
+    <standard>
+    <![CDATA[
+    There should be no trailing whitespace at the end of lines.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: No whitespace found at end of line.">
+        <![CDATA[
+echo 'semicolon followed by new line char';
+        ]]>
+        </code>
+        <code title="Invalid: Whitespace found at end of line.">
+        <![CDATA[
+echo 'trailing spaces after semicolon';<em>   </em>
+        ]]>
+        </code>
+    </code_comparison>
+    <standard>
+    <![CDATA[
+    There should be no consecutive blank lines in functions.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Functions do not contain multiple empty lines in a row.">
+        <![CDATA[
+function myFunction()
+{
+    echo 'code here';
+
+    echo 'code here';
+}
+        ]]>
+        </code>
+        <code title="Invalid: Functions contain multiple empty lines in a row.">
+        <![CDATA[
+function myFunction()
+{
+    echo 'code here';
+    <em>
+
+    </em>echo 'code here';
+}
+        ]]>
+        </code>
+    </code_comparison>
+    <standard>
+    <![CDATA[
+    There should be no superfluous whitespace after the final closing PHP tag in a file.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: A single new line appears after the last content in the file.">
+        <![CDATA[
+function myFunction()
+{
+    echo 'Closing PHP tag, then';
+    echo 'Single new line char, then EOF';
+}
+
+?><em>
+</em>
+        ]]>
+        </code>
+        <code title="Invalid: Multiple new lines appear after the last content in the file.">
+        <![CDATA[
+function myFunction()
+{
+    echo 'Closing PHP tag, then';
+    echo 'Multiple new line chars, then EOF';
+}
+
+?><em>
+
+</em>
+        ]]>
+        </code>
+    </code_comparison>
+</documentation>