Documentation: various consistency fixes

* Double checked that all existing XML docs have the `xsi` attributes and schema reference of the `<documentation>` element. * Verified that the contents of `<standard>` elements is consistently indented (with four spaces). * Verified that all `<code>` `title` attributes use proper punctuation.
jrfnl · Jul 22, 2024 · 0098653 · 0098653
1 parent d77b020
commit 0098653
Show file tree

Hide file tree

Showing 11 changed files with 36 additions and 32 deletions.
diff --git a/WordPress/Docs/Arrays/ArrayIndentationStandard.xml b/WordPress/Docs/Arrays/ArrayIndentationStandard.xml
@@ -5,18 +5,18 @@
     >
     <standard>
     <![CDATA[
-      The array closing bracket indentation should line up with the start of the content on the line containing the array opener.
+    The array closing bracket indentation should line up with the start of the content on the line containing the array opener.
     ]]>
     </standard>
     <code_comparison>
-        <code title="Valid: Closing bracket lined up correctly">
+        <code title="Valid: Closing bracket lined up correctly.">
         <![CDATA[
 $args = array(
     'post_id' => 22,
 <em>);</em>
         ]]>
         </code>
-        <code title="Invalid: Closing bracket lined up incorrectly">
+        <code title="Invalid: Closing bracket lined up incorrectly.">
         <![CDATA[
 $args = array(
     'post_id' => 22,
@@ -26,11 +26,11 @@ $args = array(
     </code_comparison>
     <standard>
     <![CDATA[
-      In multi-line arrays, array items should be indented by a 4-space tab for each level of nested array, so that the array visually matches its structure.
+    In multi-line arrays, array items should be indented by a 4-space tab for each level of nested array, so that the array visually matches its structure.
     ]]>
     </standard>
     <code_comparison>
-        <code title="Valid: Correctly indented array">
+        <code title="Valid: Correctly indented array.">
         <![CDATA[
 $args = array(
     'post_id'       => 22,
@@ -88,7 +88,7 @@ $args = array(
         </code>
     </code_comparison>
     <code_comparison>
-        <code title="Valid: Opener and comma after closer are indented correctly">
+        <code title="Valid: Opener and comma after closer are indented correctly.">
         <![CDATA[
 $text = array(
     <<<EOD

diff --git a/WordPress/Docs/Arrays/ArrayKeySpacingRestrictionsStandard.xml b/WordPress/Docs/Arrays/ArrayKeySpacingRestrictionsStandard.xml
@@ -5,11 +5,11 @@
     >
     <standard>
     <![CDATA[
-      When referring to array items, only include a space around the index if it is a variable or the key is concatenated.
+    When referring to array items, only include a space around the index if it is a variable or the key is concatenated.
     ]]>
     </standard>
     <code_comparison>
-        <code title="Valid: Correct spacing around the index keys">
+        <code title="Valid: Correct spacing around the index keys.">
         <![CDATA[
 $post       = $posts<em>[ </em>$post_id<em> ]</em>;
 $post_title = $post<em>[ </em>'concatenated' . $title<em> ]</em>;
@@ -18,7 +18,7 @@ $post       = $posts<em>[</em>123<em>]</em>;
 $post_title = $post<em>[</em>'post_title'<em>]</em>;
         ]]>
         </code>
-        <code title="Invalid: Incorrect spacing around the index keys">
+        <code title="Invalid: Incorrect spacing around the index keys.">
         <![CDATA[
 $post       = $posts<em>[</em>$post_id<em>]</em>;
 $post_title = $post<em>[</em>'concatenated' . $title<em> ]</em>;

diff --git a/WordPress/Docs/Arrays/MultipleStatementAlignmentStandard.xml b/WordPress/Docs/Arrays/MultipleStatementAlignmentStandard.xml
@@ -5,7 +5,7 @@
     >
     <standard>
     <![CDATA[
-        When declaring arrays, there should be one space on either side of a double arrow operator used to assign a value to a key.
+    When declaring arrays, there should be one space on either side of a double arrow operator used to assign a value to a key.
     ]]>
     </standard>
     <code_comparison>
@@ -24,7 +24,7 @@ $bar = array( 'year'<em>=>   </em>$current_year );
     </code_comparison>
     <standard>
     <![CDATA[
-        In the case of a block of related assignments, it is recommended to align the arrows to promote readability.
+    In the case of a block of related assignments, it is recommended to align the arrows to promote readability.
     ]]>
     </standard>
     <code_comparison>

diff --git a/WordPress/Docs/NamingConventions/PrefixAllGlobalsStandard.xml b/WordPress/Docs/NamingConventions/PrefixAllGlobalsStandard.xml
@@ -15,7 +15,7 @@
     ]]>
     </standard>
     <code_comparison>
-        <code title="Valid: Using the prefix ECPT_">
+        <code title="Valid: Using the prefix ECPT_.">
         <![CDATA[
 define( <em>'ECPT_VERSION'</em>, '1.0' );
 
@@ -29,7 +29,7 @@ apply_filter(
 );
         ]]>
         </code>
-        <code title="Invalid: non-prefixed code">
+        <code title="Invalid: non-prefixed code.">
         <![CDATA[
 define( <em>'PLUGIN_VERSION'</em>, '1.0' );
 
@@ -45,7 +45,7 @@ apply_filter(
         </code>
     </code_comparison>
     <code_comparison>
-        <code title="Valid: Using the prefix ECPT_ in namespaced code">
+        <code title="Valid: Using the prefix ECPT_ in namespaced code.">
         <![CDATA[
 namespace <em>ECPT_Plugin\Admin</em>;
 
@@ -68,7 +68,7 @@ apply_filter(
 );
         ]]>
         </code>
-        <code title="Invalid: using a non-prefixed namespace">
+        <code title="Invalid: using a non-prefixed namespace.">
         <![CDATA[
 namespace <em>Admin</em>;
 
@@ -88,12 +88,12 @@ class Admin_Page {}
     ]]>
     </standard>
     <code_comparison>
-        <code title="Valid: Using the prefix mycoolplugin_">
+        <code title="Valid: Using the prefix mycoolplugin_.">
         <![CDATA[
 function <em>mycoolplugin_save_post()</em> {}
         ]]>
         </code>
-        <code title="Invalid: Using a WordPress reserved prefix wp_">
+        <code title="Invalid: Using a WordPress reserved prefix wp_.">
         <![CDATA[
 function <em>wp_save_post()</em> {}
         ]]>
@@ -105,12 +105,12 @@ function <em>wp_save_post()</em> {}
     ]]>
     </standard>
     <code_comparison>
-        <code title="Valid: Using the distinct prefix MyPlugin">
+        <code title="Valid: Using the distinct prefix MyPlugin.">
         <![CDATA[
 interface <em>MyPluginIsCool</em> {}
         ]]>
         </code>
-        <code title="Invalid: Using a two-letter prefix My">
+        <code title="Invalid: Using a two-letter prefix My.">
         <![CDATA[
 interface <em>My</em> {}
         ]]>

diff --git a/WordPress/Docs/PHP/IniSetStandard.xml b/WordPress/Docs/PHP/IniSetStandard.xml
@@ -5,7 +5,7 @@
     >
     <standard>
     <![CDATA[
-      Using ini_set() and similar functions for altering PHP settings at runtime is discouraged. Changing runtime configuration might break other plugins and themes, and even WordPress itself.
+    Using ini_set() and similar functions for altering PHP settings at runtime is discouraged. Changing runtime configuration might break other plugins and themes, and even WordPress itself.
     ]]>
     </standard>
     <code_comparison>
@@ -22,7 +22,7 @@ ini_set( <em>'short_open_tag'</em>, 'off' );
     </code_comparison>
     <standard>
     <![CDATA[
-      For some configuration values there are alternative ways available - either via WordPress native functionality of via standard PHP - to achieve the same without the risk of breaking interoperability. These alternatives are preferred.
+    For some configuration values there are alternative ways available - either via WordPress native functionality of via standard PHP - to achieve the same without the risk of breaking interoperability. These alternatives are preferred.
     ]]>
     </standard>
     <code_comparison>

diff --git a/WordPress/Docs/PHP/YodaConditionsStandard.xml b/WordPress/Docs/PHP/YodaConditionsStandard.xml
@@ -9,14 +9,14 @@
     ]]>
     </standard>
     <code_comparison>
-        <code title="Valid: The variable is placed on the right">
+        <code title="Valid: The variable is placed on the right.">
         <![CDATA[
 if ( <em>true === $the_force</em> ) {
     $victorious = you_will( $be );
 }
         ]]>
         </code>
-        <code title="Invalid: The variable has been placed on the left">
+        <code title="Invalid: The variable has been placed on the left.">
         <![CDATA[
 if ( <em>$the_force === false</em> ) {
     $victorious = you_will_not( $be );

diff --git a/WordPress/Docs/WP/CapabilitiesStandard.xml b/WordPress/Docs/WP/CapabilitiesStandard.xml
@@ -5,7 +5,7 @@
     >
     <standard>
     <![CDATA[
-Capabilities passed should be valid capabilities (custom capabilities can be added in the ruleset).
+    Capabilities passed should be valid capabilities (custom capabilities can be added in the ruleset).
     ]]>
     </standard>
     <code_comparison>
@@ -22,7 +22,7 @@ map_meta_cap( <em>'manage_site'</em>, $user->ID );
     </code_comparison>
     <standard>
     <![CDATA[
-Always use user capabilities instead of roles.
+    Always use user capabilities instead of roles.
     ]]>
     </standard>
     <code_comparison>
@@ -51,7 +51,7 @@ add_options_page(
     </code_comparison>
     <standard>
     <![CDATA[
-Don't use deprecated capabilities.
+    Don't use deprecated capabilities.
     ]]>
     </standard>
     <code_comparison>

diff --git a/WordPress/Docs/WP/CapitalPDangitStandard.xml b/WordPress/Docs/WP/CapitalPDangitStandard.xml
@@ -5,9 +5,9 @@
     >
     <standard>
     <![CDATA[
-The correct spelling of "WordPress" should be used in text strings, comments and object names.
+    The correct spelling of "WordPress" should be used in text strings, comments and object names.
 
-In select cases, when part of an identifier or a URL, WordPress does not have to be capitalized.
+    In select cases, when part of an identifier or a URL, WordPress does not have to be capitalized.
     ]]>
     </standard>
     <code_comparison>

diff --git a/WordPress/Docs/WP/DeprecatedParametersStandard.xml b/WordPress/Docs/WP/DeprecatedParametersStandard.xml
@@ -6,7 +6,7 @@
     <standard>
     <![CDATA[
     Please refrain from passing deprecated WordPress function parameters.
-	In case, you need to pass an optional parameter positioned <em>after</em> the deprecated parameter, only ever pass the default value.
+    In case, you need to pass an optional parameter positioned <em>after</em> the deprecated parameter, only ever pass the default value.
     ]]>
     </standard>
     <code_comparison>

diff --git a/WordPress/Docs/WP/PostsPerPageStandard.xml b/WordPress/Docs/WP/PostsPerPageStandard.xml
@@ -5,9 +5,9 @@
     >
     <standard>
     <![CDATA[
-Using "posts_per_page" or "numberposts" with the value set to an high number opens up the potential for making requests slow if the query ends up querying thousands of posts.
+    Using "posts_per_page" or "numberposts" with the value set to an high number opens up the potential for making requests slow if the query ends up querying thousands of posts.
 
-You should always fetch the lowest number possible that still gives you the number of results you find acceptable.
+    You should always fetch the lowest number possible that still gives you the number of results you find acceptable.
     ]]>
     </standard>
     <code_comparison>

diff --git a/WordPress/Docs/WhiteSpace/ObjectOperatorSpacingStandard.xml b/WordPress/Docs/WhiteSpace/ObjectOperatorSpacingStandard.xml
@@ -1,4 +1,8 @@
-<documentation title="Object Operator Spacing">
+<?xml version="1.0"?>
+<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
+    title="Object Operator Spacing"
+>
     <standard>
     <![CDATA[
     The object operators (->, ?->, ::) should not have any spaces around them, though new lines are allowed except for use with the `::class` constant.